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

4.4. 参照設定の作成

クラスターの設定リソースを検証するための参照設定を指定します。

4.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>

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

4.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
#...

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

4.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 }}
    1
    指定の値と一致する必要がある必須フィールドを設定します。
    2
    任意の値を持つことができる必須フィールドを設定します。
    3
    .spec.type フィールドの検証を設定します。
    4
    任意のフィールドを設定します。

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

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

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

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

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

    注記

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

4.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
#...
    1
    true を指定して、対応する namespace.yaml テンプレートで明示的に設定されていない CR 内のすべてのフィールドを比較から除外します。

4.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

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

4.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

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

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

4.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

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

4.4.5. テンプレートフィールドのインライン検証の設定

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

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

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

4.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
    1
    インライン検証対象のフィールドを指定します。
    2
    正規表現を使用したインライン検証を有効にします。

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

    apiVersion: v1
kind: ConfigMap
metadata:
  namespace: dashboard
data:
  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.

4.4.5.2. キャプチャーグループ関数を使用したインライン検証の設定

マルチライン文字列を含むフィールドをより正確に検証するには、capturegroups インライン関数を使用します。

手順

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

    apiVersion: v2
parts:
- name: Part1
  components:
  - name: Example
    allOf:
    - path: example.yaml
      config:
        perField:
        - pathToKey: spec.bigTextBlock 1
          inlineDiffFunc: capturegroups 2
    1
    インライン検証対象のフィールドを指定します。
    2
    キャプチャーグループを使用したインライン検証を有効にします。

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

    apiVersion: v1
kind: ConfigMap
metadata:
  namespace: dashboard
data:
  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]+).

4.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
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

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

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

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

会社概要

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

© 2024 Red Hat, Inc.