Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

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. 配置模板关系
复制链接

通过在参考配置中定义模板之间的关系，您可以支持复杂依赖项的用例。例如，您可以将组件配置为需要特定的模板，需要组中的一个模板，或者允许来自组的任何模板等。

流程

  • 创建 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)，则所有对应的 CR 必须存在于集群中。
    3
    指定可选模板。
    4
    指定要排除的模板。如果集群中存在对应的 CR，则该插件会返回一个验证错误。
    5
    指定模版，其中只能有一个存在。如果集群中不存在，或有多个对应的 CR，则该插件会返回验证错误。
    6
    指定模版，其中只能有一个在集群中存在。如果集群中存在多个对应的 CR，则该插件会返回验证错误。

6.4.3. 在模板中配置预期的变体
复制链接

您可以使用 Golang 模板语法处理模板中的变量内容。使用这个语法，您可以配置处理模板中可选、必要和条件内容的验证逻辑。

注意
  • cluster-compare 插件要求所有模板呈现为有效的 YAML。为了避免解析缺失字段的错误，请在实施模板语法时使用条件模板语法，如 {{- if .spec.<optional_field> }}。此条件逻辑可确保模板正常处理缺少的字段，并保持有效的 YAML 格式。
  • 您可以将 Golang 模板语法与自定义和内置功能用于复杂用例。所有 Golang 内置功能都支持，包括 Sprig 库中的函数。

流程

  • 创建 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 插件支持所有 sprig 库函数，但 env 和 expandenv 功能除外。有关 sprig 库函数的完整列表，请参阅"Sprig Function 文档"。

下表描述了 cluster-compare 插件的额外模板功能：

Expand
表 6.2. 其他 cluster-compare 模板功能
功能描述Example

fromJson

将传入字符串解析为结构化 JSON 对象。

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

fromJsonArray

将传入字符串解析为结构化 JSON 数组。

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

fromYaml

将传入字符串解析为结构化的 YAML 对象。

值 ：{{ 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，同时保留对象类型。

对于简单的 scalar 值： value: {{ $data | toYaml }}

对于 list 或dict: value: {{ $dict | toYaml | nindent 2 }}

doNotMatch

防止模板与集群资源匹配，即使它通常匹配。您可以在模板中使用此功能，以有条件地将某些资源从关联中排除。使用 --verbose 标志运行时，指定的原因会被记录。因为 doNotMatch 不被认为是比较失败，模板被排除。

当模板没有指定固定名称或命名空间时，此功能特别有用。在这些情况下，您可以使用 doNotMatch 功能根据其他字段（如 labels 或 annotations）排除特定资源。

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

lookupCRs

返回与指定参数匹配的对象数组。例如： lookupCR $apiVersion $kind $namespace $name.

如果 $namespace 参数是空字符串("")或 *，则函数与所有命名空间匹配。对于集群范围的对象，函数与没有命名空间的对象匹配。

如果 $name 是空字符串或 *，则函数与任何命名对象匹配。

-

lookupCR

返回与参数匹配的单个对象。如果多个对象匹配，则函数返回任何内容。此功能使用与 lookupCR 函数相同的参数。

-

以下示例演示了如何使用 lookupCR 功能从多个匹配资源检索和呈现值：

使用 lookupCRs 的配置映射示例

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 的配置映射示例

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。

您可以通过在 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 组包含在 default 组中。

6.4.5. 为模板字段配置内联验证
复制链接

您可以启用内联正则表达式来验证模板字段，特别是在 Golang 模板语法难以维护或过于复杂的情况下。使用内联正则表达式可简化模板，提高可读性，并可以使用更高级的验证逻辑。

cluster-compare 插件为内联验证提供两个功能：

  • regex ：使用正则表达式验证字段中的内容。
  • capturegroups ：通过将非捕获组文本处理为完全匹配来增强多行文本比较功能，仅在指定捕获组中应用正则表达式匹配，并确保重复捕获组的一致性。

当您使用 regex 或 capturegroups 功能进行内联验证时，cluster-compare 插件会强制执行相同的命名的捕获组在模板中的多个字段中具有相同的值。这意味着，如果命名的捕获组（如 (?<username>[a-z0-9]+)) 出现在多个字段中，则该组的值必须在整个模板中保持一致。

6.4.5.1. 使用 regex 功能配置内联验证
复制链接

使用 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 功能配置内联验证
复制链接

使用 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

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat