6.4. 참조 구성 생성


클러스터의 구성 리소스의 유효성을 검사하도록 참조 구성을 구성합니다.

6.4.1. metadata.yaml 파일의 구조

metadata.yaml 파일은 참조 구성에서 템플릿을 정의하고 구성하는 중앙 구성 지점을 제공합니다. 파일에는 파트구성 요소의 계층 구조가 있습니다. 파트구성 요소 그룹이며 구성 요소는 템플릿 그룹입니다. 각 구성 요소에서 템플릿 종속 항목, 유효성 검사 규칙을 구성하고 설명 메타데이터를 추가할 수 있습니다.

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
일반적으로 모든 부분은 워크로드 또는 워크로드 집합을 설명합니다.
2
부분 이름을 지정합니다.
3
구성 요소 이름을 지정합니다.
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이 클러스터에 존재하지 않거나 둘 이상의 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 플러그인은 envexpandenv 함수를 제외한 모든 sprig 라이브러리 기능을 지원합니다. sprig 라이브러리 함수의 전체 목록은 "Sprig Function Documentation"을 참조하십시오.

다음 표에서는 클러스터 호환 플러그인의 추가 템플릿 기능을 설명합니다.

Expand
표 6.2. 추가 클러스터 호환 템플릿 기능
함수설명

fromJson

들어오는 문자열을 구조화된 JSON 오브젝트로 구문 분석합니다.

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

fromJsonArray

들어오는 문자열을 구조화된 JSON 배열로 구문 분석합니다.

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

fromYaml

들어오는 문자열을 구조화된 YAML 오브젝트로 구문 분석합니다.

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

fromYamlArray

들어오는 문자열을 구조화된 YAML 배열로 구문 분석합니다.

값: {{ obj := spec.yamltext | fromYaml}}{{ 인덱스 $obj 0 }

toJson

오브젝트 유형을 유지하면서 들어오는 데이터를 JSON으로 렌더링합니다.

jsonstring: {{ $variable | toJson }}

toToml

들어오는 문자열을 구조화된 TOML 데이터로 렌더링합니다.

tomlstring: {{ $variable | toToml }}

toYaml

오브젝트 유형을 유지하면서 들어오는 데이터를 YAML로 렌더링합니다.

간단한 스칼라 값의 경우: value: {{ $data | toYaml }}

목록 또는 사전의 경우: 값: {{ $dict | toYaml | nindent 2 }}

doNotMatch

일반적으로 일치하는 경우에도 템플릿이 클러스터 리소스와 일치하지 않습니다. 템플릿 내에서 이 함수를 사용하여 상관관계에서 특정 리소스를 조건부로 제외할 수 있습니다. --verbose 플래그를 사용하여 실행할 때 지정된 이유는 기록됩니다. doNotMatch 로 인해 제외된 템플릿은 비교 실패로 간주되지 않습니다.

이 기능은 템플릿에서 고정된 이름 또는 네임스페이스를 지정하지 않는 경우 특히 유용합니다. 이러한 경우 doNotMatch 함수를 사용하여 레이블 또는 주석 과 같은 다른 필드를 기반으로 특정 리소스를 제외할 수 있습니다.

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

lookupCRs

지정된 매개 변수와 일치하는 개체 배열을 반환합니다. 예: lookupCRs $apiVersion $kind $namespace $name.

$namespace 매개변수가 빈 문자열("") 또는 * 인 경우 함수는 모든 네임스페이스와 일치합니다. 클러스터 범위 오브젝트의 경우 함수는 네임스페이스가 없는 오브젝트와 일치합니다.

$name 이 빈 문자열 또는 * 인 경우 함수는 이름이 지정된 개체와 일치합니다.

-

lookupCR

매개 변수와 일치하는 단일 오브젝트를 반환합니다. 여러 오브젝트가 일치하면 함수는 아무것도 반환하지 않습니다. 이 함수는 lookupCRs 함수와 동일한 인수를 사용합니다.

-

다음 예제에서는 lookupCRs 함수를 사용하여 일치하는 여러 리소스에서 값을 검색하고 렌더링하는 방법을 보여줍니다.

lookupCR을 사용하는 구성 맵 예

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-fieldstrue 로 구성하는 경우 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
    해당 namespace.yaml 템플릿에 명시적으로 구성되지 않은 CR의 모든 필드를 비교에서 제외하려면 true 를 지정합니다.

6.4.4.2. 기본 제외 필드를 설정하여 특정 필드 제외

defaultOmitRef 필드에서 field ToOmitRefs의 기본값을 정의하여 필드를 제외할 수 있습니다. 이 기본 제외는 특정 템플릿에 대한 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 템플릿의 ToOmit.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
    공통 그룹은 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. 캡처 그룹 함수를 사용하여 인라인 검증 구성

여러 줄 문자열이 포함된 필드를 보다 정확하게 확인하려면 캡처 그룹 인라인 함수를 사용합니다. 이 함수는 또한 이름이 동일한 캡처 그룹이 여러 필드에서 동일한 값을 갖도록 합니다.

프로세스

  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 필드의 username 값과 big CryostatBlock 에서 캡처된 값이 일치하지 않는 경우 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은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

Theme

© 2025 Red Hat