Kustomize로 Kubernetes 구성

Kustomize는 템플릿 없는 YAML 파일을 맞춤설정하여 원래 파일을 그대로 유지하는 Kubernetes 구성 변환 도구입니다. Kustomize는 다른 표현에서 ConfigMaps 및 보안 비밀과 같은 리소스를 생성할 수도 있습니다. Kustomize는 Kubernetes API용으로 빌드되었으므로 Kubernetes 스타일 객체를 이해하고 수정할 수 있습니다.

구성 동기화와 함께 Helm 차트를 사용하려는 경우 Kustomize를 통해 Helm을 렌더링하거나 Helm API를 사용하는 두 가지 방법이 지원됩니다. 이 페이지에서는 Kustomize를 통해 Helm 차트를 렌더링하는 데 필요한 사항을 자세히 설명합니다. Helm API 사용에 대한 자세한 내용은 Artifact Registry에서 Helm 차트 동기화를 참조하세요.

Kustomize를 사용하여 Helm 차트를 렌더링할 때의 차이점은 다음과 같습니다.

  • 비공개 및 OCI 기반 Helm 레지스트리가 지원되지 않습니다. Helm API를 사용하면 비공개 및 OCI 기반 레지스트리가 모두 지원됩니다.
  • Helm 값은 정보 소스에서 관리할 수 있습니다. Helm API를 사용하면 RootSync 또는 RepoSync API의 일부로 값이 관리됩니다.
  • RootSync 또는 RepoSync 객체에서 여러 Helm 차트를 렌더링할 수 있습니다. Helm API를 사용하면 RootSync 또는 RepoSync 객체에 Helm 차트를 하나만 렌더링할 수 있습니다.

Kustomize의 구성 동기화 요구사항

Kustomize 구성 및 Helm 차트를 자동으로 렌더링하려면 구성 동기화 환경이 다음 요구사항을 충족하는지 확인합니다.

  • 비정형 정보 소스를 사용합니다. 자동 렌더링은 계층적 저장소에서 지원되지 않습니다.
  • 렌더링 프로세스를 트리거하려면 정보 소스의 루트 디렉터리에 Kustomization 구성 파일(kustomization.yaml, kustomization.yml, Kustomization)이 있어야 합니다. 루트 디렉터리에 Kustomization 구성 파일이 없으면 구성 동기화가 렌더링 없이 있는 그대로 구성을 동기화합니다.
  • kustomization.yaml 파일에 구성을 포함합니다. 이러한 구성 파일을 포함하지 않으면 구성이 클러스터에 동기화되지 않습니다.
  • 구성 동기화 1.19.0 이전에는 모든 구성을 Kustomization 루트 디렉터리에 포함해야 했습니다. 버전 1.19.0부터 구성 동기화는 루트 디렉터리 외부의 파일을 지원합니다.

Kustomize 구성 렌더링

다음 예시에서는 자동 렌더링과 함께 Kustomize 구성을 사용하도록 정보 소스를 설정하는 방법을 보여줍니다.

Kustomize 구성의 아키텍처 예시

이 디렉터리에는 동일한 기반을 참조하는 4개의 오버레이(team-a, team-b, team-c, external-team) 및 ConfigMap 생성기에서 사용하는 파일이 포함되어 있습니다.

다음 다이어그램은 디렉터리 구조를 보여줍니다.

├── example
│   ├── base
│   │   ├── kustomization.yaml
│   │   ├── namespace.yaml
│   │   ├── networkpolicy.yaml
│   │   ├── rolebinding.yaml
│   │   └── role.yaml
│   ├── kustomization.yaml
│   ├── README.md
│   ├── team-a
│   │   └── kustomization.yaml
│   ├── team-b
│   │   └── kustomization.yaml
│   └── team-c
│       └── kustomization.yaml
├── external-team
│   └── kustomization.yaml
└── external-data.txt

다음 kustomization.yaml 파일은 정보 소스의 루트에 있으며 로컬 파일의 ConfigMap 생성기를 포함하는 4개의 오버레이 참조를 포함합니다.

# ./example/kustomization.yaml
resources:
- team-a
- team-b
- team-c
- ../external-team # Starting from 1.19.0, Config Sync allows external resources located outside of the Kustomization root directory.

configMapGenerator:
- name: my-configmap
  namespace: my-namespace
  files:
    - ../external-data.txt # Starting from 1.19.0, Config Sync allows external files located outside of the Kustomization root directory.

다음 kustomize.yaml은 team-a 디렉터리에 있으며 team-a의 오버레이입니다.

# ./example/team-a/kustomization.yaml
namespace: team-a

resources:
- ../base

patches:
- target:
   kind: RoleBinding
   name: team-admin-rolebinding
  patch: |-
    - op: replace
      path: /subjects/0/name
      value: team-a-admin@mydomain.com
- target:
   kind: Namespace
   name: default
  patch: |-
    - op: replace
      path: /metadata/name
      value: team-a

다음 kustomization.yaml은 base 디렉터리에 있으며 Kustomize 기본 항목입니다.

# ./example/base/kustomization.yaml
resources:
- namespace.yaml
- rolebinding.yaml
- role.yaml
- networkpolicy.yaml

GitHub의 네임스페이스 관련 정책 구성 디렉터리에서 예시 저장소를 살펴볼 수 있습니다.

Kustomize를 통해 Helm 차트 렌더링

이 섹션에서는 Kustomize를 통해 Helm 차트를 렌더링하는 방법을 설명합니다. 번들 Helm 및 Kustomize 버전은 구성 동기화의 해당 버전과 함께 번들로 제공되는 Kustomize 및 Helm 버전을 나열합니다.

Helm 차트 필드

Kustomize를 통해 Helm 차트 렌더링을 지원하도록 kustomization.yaml 파일에 다음 Helm 차트 필드를 추가할 수 있습니다.

필드 설명
helmGlobals 모든 Helm 차트에 적용되는 매개변수
helmGlobals.chartHome 문자열을 허용합니다. Kustomization 루트에 상대되는 Kustomization에 포함할 각 차트의 하위 디렉터리가 있는 디렉터리에 대한 경로입니다. 이 필드의 기본값은 charts입니다.
helmGlobals.configHome 문자열을 허용합니다. Kustomize가 HELM_CONFIG_HOME 환경 변수로 Helm으로 전달할 값을 정의합니다. Kustomize는 이 디렉터리에 대해 읽기 또는 쓰기를 시도하지 않습니다. 생략하면 TMP_DIR/helm이 사용됩니다. 여기서 TMP_DIR은 Helm에 대해 Kustomize에서 생성된 임시 디렉터리입니다.
helmCharts Helm 차트 매개변수의 배열
helmCharts.name 문자열을 허용합니다. 차트 이름입니다. 필수 필드입니다.
helmCharts.version 문자열을 허용합니다. 차트 버전
helmCharts.repo 문자열을 허용합니다. 차트를 찾는 데 사용되는 URL
helmCharts.releaseName 문자열을 허용합니다. 차트 템플릿 출력에서 RELEASE_NAME을 바꿉니다.
helmCharts.namespace 문자열을 허용합니다. 출시의 대상 네임스페이스를 설정합니다(템플릿의 .Release.Namespace).
helmCharts.valuesInline 차트에 포함되는 기본값 대신 사용할 값
helmCharts.valuesFile 문자열을 허용합니다. ValuesFile은 차트에 포함된 기본값 대신 사용할 값 파일에 대한 로컬 경로 또는 원격 URL입니다. 기본값은 CHART_HOME/NAME/values.yaml에 있습니다.
helmCharts.valuesMerge merge, override, (default), replace를 허용합니다. ValuesMerge는 값에 따라 ValuesInline 처리 방법을 지정합니다.
helmCharts.includeCRDs true 또는 false를 허용합니다. Helm이 CustomResourceDefinitions도 생성해야 하는지 여부를 지정합니다. 기본값은 false입니다.

원격 Helm 차트 렌더링

구성 동기화는 공개 인터넷 액세스가 권한이 있는 클러스터에서 원격 Helm 차트를 렌더링하도록 지원합니다.

다음 kustomization.yaml은 다음 helmCharts 필드를 설정하여 원격 cert-manager를 렌더링합니다.

# ./kustomization.yaml
...
helmCharts:
- name: cert-manager
  repo: https://charts.jetstack.io
  version: v1.5.3
  releaseName: my-cert-manager
  namespace: cert-manager
...

로컬 Helm 차트 렌더링

구성 동기화는 로컬 Helm 차트 렌더링을 지원합니다. 맞춤설정된 Helm 차트 버전을 사용하려면 Helm 차트(예: ArtifactHub)에서 출시된 버전을 가져와 로컬로 변경한 후 변경사항을 정보 소스에 푸시합니다.

다음 다이어그램은 디렉터리 구조를 보여줍니다.

├── base
│   ├── charts
│   │   └── cert-manager
│   └── kustomization.yaml
├── overlays
│   └── stage
│       └── kustomization.yaml
└── base_value_overrides.yaml

다음 kustomization.yaml은 로컬 cert-manager 차트를 렌더링합니다. Helm 차트의 기본 디렉터리는 charts이고, 이 차트가 charts 디렉터리에 체크인되기 때문에 .helmCharts.repo 또는 .helmCharts.version을 지정할 필요가 없습니다.

# ./overlays/stage/kustomization.yaml
...
# This field is optional if your Helm charts are located in the default 'charts' directory.
helmGlobals:
  # Starting from 1.19.0, Config Sync allows loading from an external directory outside of the Kustomization root.
  chartHome: ../../base/charts
helmCharts:
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
  # Specify a local path or a remote URL to a values file instead of using the default values in CHART_HOME/NAME/values.yaml.
  valuesFile: ../../base_value_overrides.yaml
...

여러 Helm 차트 렌더링

구성 동기화는 차트가 원격 또는 로컬인지 여부에 관계없이 하나의 kustomization.yaml 파일에서 여러 Helm 차트 렌더링을 지원합니다.

다음 kustomization.yaml은 로컬 Helm 차트(cert-manager)를 렌더링합니다.

# ./kustomization.yaml
...
helmCharts:
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
- name: prometheus
  repo: https://prometheus-community.github.io/helm-charts
  version: 14.3.0
  releaseName: my-prometheus
  namespace: monitoring
...

다음 단계