Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

6.4. リファレンス設定の作成

クラスターの設定リソースを検証するためのリファレンス設定を指定します。

6.4.1. metadata.yaml ファイルの構造
リンクのコピー

metadata.yaml ファイルは、リファレンス設定のテンプレートを一元的に定義および設定するため場所です。このファイルには、parts と components という階層が含まれています。parts は components のグループであり、components はテンプレートのグループです。各コンポーネントで、テンプレートの依存関係、検証ルールを設定し、説明的なメタデータを追加できます。

metadata.yaml ファイルの例

apiVersion: v2
parts:
1 

  - name: Part1
2 

    components:
      - name: Component1
3 

        <component1_configuration>
4 

  - name: Part2
      - name: Component2
        <component2_configuration>
Copy to Clipboard Toggle word wrap

1
各 part には、通常、ワークロードまたはワークロードのセットを記述します。
2
part の名前を指定します。
3
component の名前を指定します。
4
テンプレートの設定を指定します。たとえば、テンプレートの関係を定義したり、比較で使用するフィールドを設定したりします。

6.4.2. テンプレートの関係の設定
リンクのコピー

リファレンス設定でテンプレート間の関係を定義することで、複雑な依存関係を伴うユースケースに対応できます。たとえば、特定のテンプレートを要求するコンポーネントを設定したり、グループから 1 つのテンプレートを要求するコンポーネントを設定したり、グループからのすべてのテンプレートを許可するコンポーネントを設定できます。

手順

  • ユースケースに合わせて metadata.yaml ファイルを作成します。例として次の構造を使用します。

    metadata.yaml ファイルの例

    apiVersion: v2
parts:
  - name: Part1
    components:
      - name: Component1
        allOf:
    1 
    
          - path: RequiredTemplate1.yaml
          - path: RequiredTemplate2.yaml
      - name: Component2
        allOrNoneOf:
    2 
    
          - path: OptionalBlockTemplate1.yaml
          - path: OptionalBlockTemplate2.yaml
      - name: Component3
        anyOf:
    3 
    
          - path: OptionalTemplate1.yaml
          - path: OptionalTemplate2.yaml
      - name: Component4
        noneOf:
    4 
    
          - path: BannedTemplate1.yaml
          - path: BannedTemplate2.yaml
      - name: Component5
        oneOf:
    5 
    
          - path: RequiredExclusiveTemplate1.yaml
          - path: RequiredExclusiveTemplate2.yaml
      - name: Component6
        anyOneOf:
    6 
    
          - path: OptionalExclusiveTemplate1.yaml
          - path: OptionalExclusiveTemplate2.yaml
#...
    Copy to Clipboard Toggle word wrap

    1
    必要なテンプレートを指定します。
    2
    すべて必須またはすべて任意のテンプレートのグループを指定します。クラスター内に対応するカスタムリソース (CR) が 1 つ存在する場合、クラスター内に対応するすべての CR が存在する必要があります。
    3
    任意のテンプレートを指定します。
    4
    除外するテンプレートを指定します。対応する CR がクラスター内に存在する場合、プラグインが検証エラーを返します。
    5
    1 つだけ存在できるテンプレートを指定します。対応する CR がクラスター内に存在する場合、または 1 つ以上存在する場合、プラグインが検証エラーを返します。
    6
    クラスター内に 1 つだけ存在できるテンプレートを指定します。対応する CR がクラスター内に複数存在する場合、プラグインが検証エラーを返します。

6.4.3. テンプレートで想定内の差異を設定する
リンクのコピー

Golang テンプレート構文を使用すると、テンプレート内の可変的な内容を処理できます。この構文を使用すると、テンプレート内の任意、必須、および条件付きの内容を処理する検証ロジックを設定できます。

注記
  • cluster-compare プラグインでは、すべてのテンプレートを有効な YAML としてレンダリングする必要があります。フィールドの欠落による解析エラーを回避するには、テンプレート構文を実装するときに {{- if .spec.<optional_field> }} などの条件付きテンプレート構文を使用してください。このような条件付きロジックを使用すると、テンプレートでフィールドの欠落が適切に処理され、有効な YAML 形式が維持されます。
  • 複雑なユースケースの場合は、カスタム関数と組み込み関数を使用した Golang テンプレート構文を使用できます。Sprig ライブラリーの関数を含むすべての Golang 組み込み関数がサポートされています。

手順

  • ユースケースに合わせて metadata.yaml ファイルを作成します。例として次の構造を使用します。 

    apiVersion: v2
kind: Service
metadata:
  name: frontend
    1 
    
  namespace: {{ .metadata.namespace }}
    2 
    
  labels:
    app: guestbook
    tier: frontend
spec:
  {{- if and .spec.type (eq (.spec.type) "NodePort" "LoadBalancer") }}
  type: {{.spec.type }}
    3 
    
  {{- else }}
  type: should be NodePort or LoadBalancer
  {{- end }}
  ports:
  - port: 80
  selector:
    app: guestbook
    {{- if .spec.selector.tier }}
    4 
    
    tier: frontend
    {{- end }}
    Copy to Clipboard Toggle word wrap
    1
    指定の値と一致する必要がある必須フィールドを設定します。
    2
    任意の値を持つことができる必須フィールドを設定します。
    3
    .spec.type フィールドの検証を設定します。
    4
    任意のフィールドを設定します。

6.4.3.1. リファレンステンプレート関数
リンクのコピー

cluster-compare プラグインは、env 関数と expandenv 関数を除くすべての sprig ライブラリー関数をサポートします。sprig ライブラリー関数の完全なリストは、「Sprig Function Documentation」を参照してください。

次の表は、cluster-compare プラグインの追加のテンプレート関数を説明しています。

Expand
表6.2 追加の cluster-compare テンプレート関数
機能説明例

fromJson

受信した文字列を構造化 JSON オブジェクトとして解析します。

value: {{ obj := spec.jsontext | fromJson }}{{ obj.field }}

fromJsonArray

受信した文字列を構造化 JSON 配列として解析します。

value: {{ obj := spec.jsontext | fromJson}}{{ index $obj 0 }}

fromYaml

受信した文字列を構造化 YAML オブジェクトとして解析します。

value: {{ obj := spec.yamltext | fromYaml }}{{ obj.field }}

fromYamlArray

受信した文字列を構造化 YAML 配列として解析します。

value: {{ obj := spec.yamltext | fromYaml}}{{ index $obj 0 }

toJson

オブジェクトタイプを保持しながら、受信したデータを JSON 形式でレンダリングします。

jsonstring: {{ $variable | toJson }}

toToml

受信した文字列を構造化 TOML データとしてレンダリングします。

tomlstring: {{ $variable | toToml }}

toYaml

オブジェクトタイプを保持しながら、受信したデータを YAML 形式でレンダリングします。

単純なスカラー値の場合: value: {{ $data | toYaml }}

リストまたはディクショナリーの場合: value: {{ $dict | toYaml | nindent 2 }}

doNotMatch

通常はマッチするテンプレートでも、クラスターリソースとマッチしないようにします。テンプレート内でこの関数を使用すると、条件に応じて特定のリソースを相関付けから除外できます。--verbose フラグを付けて実行すると、指定した理由がログに記録されます。doNotMatch により除外されたテンプレートが、比較で不合格とみなされることはありません。

この関数は、テンプレートで固定の名前または namespace が指定されていない場合に特に便利です。このような場合、doNotMatch 関数を使用すると、labels や annotations などの他のフィールドに基づいて特定のリソースを除外できます。

{{ if $condition }}{{ doNotMatch $reason }}{{ end }}

lookupCRs

指定されたパラメーターにマッチするオブジェクトの配列を返します。たとえば、lookupCRs $apiVersion $kind $namespace $name などです。

$namespace パラメーターが空の文字列 ("") または * の場合、この関数はすべての namespace にマッチします。クラスタースコープのオブジェクトの場合、この関数は namespace のないオブジェクトにマッチします。

$name が空の文字列または * の場合、この関数はすべての名前付きオブジェクトにマッチします。

-

lookupCR

パラメーターにマッチする単一のオブジェクトを返します。複数のオブジェクトがマッチする場合、この関数は何も返しません。この関数は lookupCRs 関数と同じ引数を取ります。

-

次の例は、lookupCRs 関数を使用して、マッチする複数のリソースから値を取得してレンダリングする方法を示しています。

lookupCRs を使用した config map の例

kind: ConfigMap
apiVersion: v1
metadata:
  labels:
    k8s-app: kubernetes-dashboard
  name: kubernetes-dashboard-settings
  namespace: kubernetes-dashboard
data:
  dashboard: {{ index (lookupCR "apps/v1" "Deployment" "kubernetes-dashboard" "kubernetes-dashboard") "metadata" "name" \| toYaml }}
  metrics: {{ (lookupCR "apps/v1" "Deployment" "kubernetes-dashboard" "dashboard-metrics-scraper").metadata.name \| toYaml }}
Copy to Clipboard Toggle word wrap

次の例は、lookupCR 関数を使用して、マッチする単一のリソースから特定の値を取得して使用する方法を示しています。

lookupCR を使用した config map の例

kind: ConfigMap
apiVersion: v1
metadata:
  labels:
    k8s-app: kubernetes-dashboard
  name: kubernetes-dashboard-settings
  namespace: kubernetes-dashboard
data:
  {{- $objlist := lookupCRs "apps/v1" "Deployment" "kubernetes-dashboard" "*" }}
  {{- $dashboardName := "unknown" }}
  {{- $metricsName := "unknown" }}
  {{- range $obj := $objlist }}
    {{- $appname := index $obj "metadata" "labels" "k8s-app" }}
    {{- if contains "metrics" $appname }}
      {{- $metricsName = $obj.metadata.name }}
    {{- end }}
    {{- if eq "kubernetes-dashboard" $appname }}
      {{- $dashboardName = $obj.metadata.name }}
    {{- end }}
  {{- end }}
  dashboard: {{ $dashboardName }}
  metrics: {{ $metricsName }}
Copy to Clipboard Toggle word wrap

6.4.4. テンプレートフィールドを除外するための metadata.yaml ファイルの設定
リンクのコピー

比較からフィールドを除外するように metadata.yaml ファイルを設定できます。クラスター設定に関係のないアノテーションやラベルなど、比較に関係のないフィールドは除外します。

次の方法で、metadata.yaml ファイルで除外を設定できます。

  • テンプレートで指定されていないカスタムリソース内のすべてのフィールドを除外する。

  • pathToKey フィールドを使用して定義した特定のフィールドを除外する。

    注記

    pathToKey はドットで区切りのパスです。ピリオドを含むキー値をエスケープするには、引用符を使用してください。

6.4.4.1. テンプレートで指定されていないすべてのフィールドを除外する
リンクのコピー

比較プロセス中に、cluster-compare プラグインは、対応するカスタムリソース (CR) のフィールドをマージしてテンプレートをレンダリングします。ignore-unspecified-fields を true に設定すると、CR に存在するがテンプレートには存在しないすべてのフィールドがマージから除外されます。テンプレートで指定したフィールドのみを比較対象にする場合は、この方法を使用します。

手順

  • ユースケースに合わせて metadata.yaml ファイルを作成します。例として次の構造を使用します。 

    apiVersion: v2
parts:
  - name: Part1
    components:
      - name: Namespace
        allOf:
          - path: namespace.yaml
            config:
              ignore-unspecified-fields: true
    1 
    
#...
    Copy to Clipboard Toggle word wrap
    1
    true を指定して、対応する namespace.yaml テンプレートで明示的に設定されていない CR 内のすべてのフィールドを比較から除外します。

6.4.4.2. デフォルトの除外フィールドを設定して特定のフィールドを除外する
リンクのコピー

defaultOmitRef フィールドの fieldsToOmitRefs のデフォルト値を定義することで、フィールドを除外できます。このデフォルトの除外は、特定のテンプレートの config.fieldsToOmitRefs フィールドによってオーバーライドされない限り、すべてのテンプレートに適用されます。

手順

  • ユースケースに合わせて metadata.yaml ファイルを作成します。例として次の構造を使用します。

    metadata.yaml ファイルの例

    apiVersion: v2
parts:

#...

fieldsToOmit:
   defaultOmitRef: default
    1 
    
   items:
      default:
         - pathToKey: a.custom.default."k8s.io"
    2
    Copy to Clipboard Toggle word wrap

    1
    特定のテンプレートの config.fieldsToOmitRefs フィールドによってオーバーライドされない限り、全テンプレートのデフォルトの除外を設定します。
    2
    この値がすべてのテンプレートから除外されます。

6.4.4.3. 特定のフィールドを除外する
リンクのコピー

フィールドへのパスを定義し、テンプレートの config セクションでその定義を参照することで、除外するフィールドを指定できます。

手順

  • ユースケースに合わせて metadata.yaml ファイルを作成します。例として次の構造を使用します。

    metadata.yaml ファイルの例

    apiVersion: v2
parts:
  - name: Part1
    components:
      - name: Component1
        - path: deployment.yaml
          config:
            fieldsToOmitRefs:
              - deployments
    1 
    

#...

fieldsToOmit:
   items:
      deployments:
         - pathToKey: spec.selector.matchLabels.k8s-app
    2
    Copy to Clipboard Toggle word wrap

    1
    deployment.yaml テンプレートの fieldsToOmit.items.deployments 項目を参照します。
    2
    spec.selector.matchLabels.k8s-app フィールドを比較から除外します。
    注記

    fieldsToOmitRefs を設定すると、デフォルト値が置き換えられます。

6.4.4.4. デフォルトの除外グループを設定して特定のフィールドを除外する
リンクのコピー

除外するフィールドのデフォルトグループを作成できます。除外グループは、除外を定義するときに重複を避けるために、別のグループを参照できます。

手順

  • ユースケースに合わせて metadata.yaml ファイルを作成します。例として次の構造を使用します。

    metadata.yaml ファイルの例

    apiVersion: v2
parts:

#...

fieldsToOmit:
   defaultOmitRef: default
   items:
    common:
      - pathToKey: metadata.annotations."kubernetes.io/metadata.name"
      - pathToKey: metadata.annotations."kubernetes.io/metadata.name"
      - pathToKey: metadata.annotations."kubectl.kubernetes.io/last-applied-configuration"
      - pathToKey: metadata.creationTimestamp
      - pathToKey: metadata.generation
      - pathToKey: spec.ownerReferences
      - pathToKey: metadata.ownerReferences
    default:
      - include: common
    1 
    
      - pathToKey: status
    Copy to Clipboard Toggle word wrap

    1
    common グループがデフォルトグループに含まれます。

6.4.5. テンプレートフィールドのインライン検証の設定
リンクのコピー

特に Golang テンプレート構文のメンテナンスが困難な場合や複雑すぎる場合は、インライン正規表現を有効にしてテンプレートフィールドを検証できます。インライン正規表現を使用すると、テンプレートが簡素化され、可読性が向上し、より高度な検証ロジックが可能になります。

cluster-compare プラグインには、インライン検証用の 2 つの関数があります。

  • regex: 正規表現を使用してフィールドの内容を検証します。
  • capturegroups: キャプチャーグループ以外のテキストを完全一致として処理し、名前付きキャプチャーグループ内でのみ正規表現マッチングを適用し、繰り返しキャプチャーグループの一貫性を確保することで、マルチラインテキストの比較を強化します。

インライン検証に regex または capturegroups 関数のいずれかを使用する場合、cluster-compare プラグインは、テンプレート内の複数のフィールドにわたって、同じ名前のキャプチャーグループが同じ値を持つことを強制します。つまり、(?<username>[a-z0-9]+) などの名前付きキャプチャーグループが複数のフィールドに現れる場合、そのグループの値がテンプレート全体で一貫している必要があります。

6.4.5.1. 正規表現関数を使用したインライン検証の設定
リンクのコピー

正規表現を使用してフィールドを検証するには、regex インライン関数を使用します。

手順

  1. ユースケースに合わせて metadata.yaml ファイルを作成します。例として次の構造を使用します。 

    apiVersion: v2
parts:
- name: Part1
  components:
  - name: Example
    allOf:
    - path: example.yaml
      config:
        perField:
        - pathToKey: spec.bigTextBlock
    1 
    
          inlineDiffFunc: regex
    2
    Copy to Clipboard Toggle word wrap
    1
    インライン検証の対象とするフィールドを指定します。
    2
    正規表現を使用したインライン検証を有効にします。

  2. 正規表現を使用して、関連するテンプレートのフィールドを検証します。 

    apiVersion: v1
kind: ConfigMap
metadata:
  namespace: dashboard
data:
  username: "(?<username>[a-z0-9]+)"
  bigTextBlock: |-
    This is a big text block with some static content, like this line.
    It also has a place where (?<username>[a-z0-9]+) would put in their own name. (?<username>[a-z0-9]+) would put in their own name.
    Copy to Clipboard Toggle word wrap

6.4.5.2. キャプチャーグループ関数を使用したインライン検証の設定
リンクのコピー

マルチライン文字列を含むフィールドをより正確に検証するには、capturegroups インライン関数を使用します。この関数は、複数のフィールドにわたって、同じ名前のキャプチャーグループが同じ値を持つことを確認します。

手順

  1. ユースケースに合わせて metadata.yaml ファイルを作成します。例として次の構造を使用します。 

    apiVersion: v2
parts:
- name: Part1
  components:
  - name: Example
    allOf:
    - path: example.yaml
      config:
        perField:
        - pathToKey: data.username
    1 
    
          inlineDiffFunc: regex
    2 
    
        - pathToKey: spec.bigTextBlock
    3 
    
          inlineDiffFunc: capturegroups
    4
    Copy to Clipboard Toggle word wrap
    1
    インライン検証の対象とするフィールドを指定します。
    2
    キャプチャーグループを使用したインライン検証を有効にします。
    3
    キャプチャーグループ検証の対象とするマルチラインフィールドを指定します。
    4
    キャプチャーグループを使用したインライン検証を有効にします。

  2. 正規表現を使用して、関連するテンプレートのフィールドを検証します。 

    apiVersion: v1
kind: ConfigMap
metadata:
  namespace: dashboard
data:
  username: "(?<username>[a-z0-9]+)"
    1 
    
  bigTextBlock: |-
    This static content outside of a capture group should match exactly.
    Here is a username capture group: (?<username>[a-z0-9]+).
    It should match this capture group: (?<username>[a-z0-9]+).
    Copy to Clipboard Toggle word wrap
    1
    data.username フィールドのユーザー名の値と bigTextBlock でキャプチャーされた値が一致しない場合、cluster-compare プラグインは不一致に関する警告を出力します。

    不一致に関する警告を含む出力例:

    WARNING: Capturegroup (?<username>…) matched multiple values: « mismatchuser | exampleuser »
    Copy to Clipboard Toggle word wrap

6.4.6. 出力の説明の設定
リンクのコピー

各パーツ、コンポーネント、またはテンプレートに、追加のコンテキスト、手順、またはドキュメントリンクを提供するための説明を含めることができます。これらの説明は、特定のテンプレートまたは構造が必要な理由を伝えるのに役立ちます。

手順

  • ユースケースに合わせて metadata.yaml ファイルを作成します。例として次の構造を使用します。 

    apiVersion: v2
parts:
  - name: Part1
    description: |-
      General text for every template under this part, unless overridden.
    components:
      - name: Component1
        # With no description set, this inherits the description from the part above.
        OneOf:
          - path: Template1.yaml
            # This inherits the component description, if set.
          - path: Template2.yaml
          - path: Template3.yaml
            description: |-
              This template has special instructions that don't apply to the others.
      - name: Component2
        description: |-
          This overrides the part text with something more specific.
          Multi-line text is supported, at all levels.
        allOf:
          - path: RequiredTemplate1.yaml
          - path: RequiredTemplate2.yaml
            description: |-
              Required for important reasons.
          - path: RequiredTemplate3.yaml
    Copy to Clipboard Toggle word wrap
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat