차트

Helm은 *차트(charts)*라는 패키징 형식을 사용해요. 차트는 관련된 Kubernetes 리소스 집합을 설명하는 파일들의 모음이에요. 단일 차트는 memcached 파드처럼 간단한 것을 배포하거나, HTTP 서버·데이터베이스·캐시 등을 갖춘 완전한 웹 앱 스택처럼 복잡한 것을 배포하는 데 사용될 수 있어요.

차트는 특정 디렉터리 트리로 배치된 파일들로 만들어져요. 배포를 위해 버전이 붙은 아카이브로 패키징할 수 있어요.

설치하지 않고 게시된 차트의 파일을 내려 받아 살펴보려면 helm pull chartrepo/chartname으로 할 수 있어요.

이 문서는 차트 형식을 설명하고 Helm으로 차트를 만드는 기본 지침을 제공해요.

출처: 문서

본문

차트 파일 구조

차트는 디렉터리 안의 파일 모음으로 구성돼요. 디렉터리 이름은 차트의 이름이에요(버전 정보 없이). 따라서 WordPress를 설명하는 차트는 wordpress/ 디렉터리에 저장돼요.

이 디렉터리 안에서 Helm은 다음 구조를 기대해요:

wordpress/
  Chart.yaml          # A YAML file containing information about the chart
  LICENSE             # OPTIONAL: A plain text file containing the license for the chart
  README.md           # OPTIONAL: A human-readable README file
  values.yaml         # The default configuration values for this chart
  values.schema.json  # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file
  charts/             # A directory containing any charts upon which this chart depends.
  crds/               # Custom Resource Definitions
  templates/          # A directory of templates that, when combined with values,
                      # will generate valid Kubernetes manifest files.
  templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes

Helm은 charts/, crds/, templates/ 디렉터리와 나열된 파일 이름의 사용을 예약해요. 다른 파일은 그대로 남겨 둬요.

Chart.yaml 파일

차트에는 Chart.yaml 파일이 필요해요. 이 파일은 다음 필드를 담아요:

apiVersion: The chart API version (required)
name: The name of the chart (required)
version: The version of the chart (required)
kubeVersion: A SemVer range of compatible Kubernetes versions (optional)
description: A single-sentence description of this project (optional)
type: The type of the chart (optional)
keywords:
  - A list of keywords about this project (optional)
home: The URL of this projects home page (optional)
sources:
  - A list of URLs to source code for this project (optional)
dependencies: # A list of the chart requirements (optional)
  - name: The name of the chart (nginx)
    version: The version of the chart ("1.2.3")
    repository: (optional) The repository URL ("https://example.com/charts") or alias ("@repo-name")
    condition: (optional) A yaml path that resolves to a boolean, used for enabling/disabling charts (e.g. subchart1.enabled )
    tags: # (optional)
      - Tags can be used to group charts for enabling/disabling together
    import-values: # (optional)
      - ImportValues holds the mapping of source values to parent key to be imported. Each item can be a string or pair of child/parent sublist items.
    alias: (optional) Alias to be used for the chart. Useful when you have to add the same chart multiple times
maintainers: # (optional)
  - name: The maintainers name (required for each maintainer)
    email: The maintainers email (optional for each maintainer)
    url: A URL for the maintainer (optional for each maintainer)
icon: A URL to an SVG or PNG image to be used as an icon (optional).
appVersion: The version of the app that this contains (optional). Needn't be SemVer. Quotes recommended.
deprecated: Whether this chart is deprecated (optional, boolean)
annotations:
  example: A list of annotations keyed by name (optional).

v3.3.2부터 추가 필드는 허용되지 않아요. 커스텀 메타데이터는 annotations에 추가하는 것을 권장해요.

차트와 버전 관리

모든 차트는 버전 번호를 가져야 해요. 버전은 SemVer 2 표준을 따라야 하지만 엄격히 강제되지는 않아요. Helm Classic과 달리 Helm v2 이상은 버전 번호를 릴리스 마커로 사용해요. 저장소의 패키지는 이름과 버전으로 식별돼요.

예를 들어 version: 1.2.3로 설정된 nginx 차트는 다음과 같이 이름이 붙어요:

nginx-1.2.3.tgz

version: 1.2.3-alpha.1+ef365처럼 더 복잡한 SemVer 2 이름도 지원돼요. 하지만 SemVer가 아닌 이름은 시스템에서 명시적으로 허용되지 않아요. 단, x 또는 x.y 형식의 버전은 예외예요. 예를 들어 앞에 v가 있거나 3부분이 모두 없는 버전(예: v1.2)은 유효한 시맨틱 버전(예: v1.2.0)으로 강제 변환을 시도해요.

참고: Helm Classic과 Deployment Manager는 차트에 관해 아주 GitHub 지향적이었지만, Helm v2 이상은 GitHub나 Git에 의존하거나 요구하지 않아요. 결과적으로 버전 관리에 Git SHA를 전혀 사용하지 않아요.

Chart.yaml의 version 필드는 CLI를 포함한 많은 Helm 도구가 사용해요. 패키지를 생성할 때 helm package 명령은 Chart.yaml에서 찾은 버전을 패키지 이름의 토큰으로 사용해요. 시스템은 차트 패키지 이름의 버전 번호가 Chart.yaml의 버전 번호와 일치한다고 가정해요. 이 가정을 어기면 오류가 발생해요.

`apiVersion` 필드

apiVersion 필드는 Helm 3 이상이 필요한 차트의 경우 v2여야 해요. 이전 Helm 버전을 지원하는 차트는 apiVersion이 v1로 설정되며 Helm 3에서도 여전히 설치할 수 있어요.

v1에서 v2로의 변경 사항:

차트 의존성을 정의하는 dependencies 필드. v1 차트에서는 별도의 requirements.yaml 파일에 있었어요.
애플리케이션 차트와 라이브러리 차트를 구분하는 type 필드.

`appVersion` 필드

appVersion 필드는 version 필드와 관련이 없다는 점에 주의해요. 애플리케이션의 버전을 지정하는 방법이에요. 예를 들어 drupal 차트는 appVersion: "8.2.1"을 가질 수 있어요.

`kubeVersion` 필드

kubeVersion 필드는 이 차트가 지원하는 Kubernetes 버전 범위를 지정하는 방법이에요. semver 제약 표현식으로 지정되며, Helm은 설치 전에 대상 Kubernetes 버전을 검증하는 데 사용할 수 있어요.

예를 들어 세밀한 버전으로 차트를 제한하려면 kubeVersion: ">= 1.19.0-0"을 지정해요. 특정 Kubernetes 마이너 버전에서만 동작하게 하려면 kubeVersion: < 1.21.0-0을 지정해요. -0 접미사가 필요한 이유는 Kubernetes 릴리스가 버전 표기에서 -0을 제거해 v1.21.0-0 대신 v1.21.0만 갖기 때문이에요.

kubeVersion: "^1.20.0"
kubeVersion: ">= 1.19.0-0"
kubeVersion: ">= 1.19.0-0 < 1.21.0-0"
kubeVersion: "< 1.21.0-0"

Kubernetes 마이너 버전이 올라갈 때 무엇을 kubeVersion 제약으로 써야 할까요? Helm 커뮤니티는 제약에서 우선순위 선호도를 사용해야 한다고 정했어요. >=와 < 연산자를 사용해요.

kubeVersion: ">= 1.19.0-0 < 1.21.0-0"

차트 deprecated 표시

Helm v3부터 Chart.yaml에서 deprecated: true를 설정해 차트를 deprecated로 표시할 수 있어요. 차트를 deprecated로 설명해도 설치 가능성은 바뀌지 않지만, 차트가 더 이상 적극적으로 유지보수되지 않는다는 사실을 사용자에게 전달해요. 특히 helm search는 그런 차트를 "deprecated"라는 단어로 표시해요.

차트 유형

차트에는 애플리케이션 차트와 라이브러리 차트 두 가지 유형이 있어요. 애플리케이션 차트(기본값)는 애플리케이션을 단순한 형태(Deployments, Jobs, Services)로 묘사하는 데만 관심이 있는 차트이며, helm create를 실행해 만들 수 있어요.

반대로 라이브러리 차트는 최종 사용자(즉, 차트 개발자)가 자신의 차트에서 재사용할 수 있는 템플릿과 기타 코드 조각을 담은 차트이며, 배포하기 위한 것이 아니에요. 자세한 내용은 라이브러리 차트를 참고하세요.

차트 LICENSE, README와 NOTES

차트는 사용법·라이선스·기타 정보를 설명하는 파일도 담을 수 있어요.

차트의 README 파일은 Markdown 형식(README.md)이어야 해요
LICENSE는 일반 텍스트 파일(LICENSE)이에요
NOTES.txt 파일은 helm install 출력의 일부로 설치 후 참고 사항을 렌더링하려면 templates/ 디렉터리에 저장해야 해요
차트는 values.yaml 파일에 구조를 부과하는 JSON 스키마인 values.schema.json 파일도 담을 수 있어요

차트는 helm dependency update 명령으로 차트 의존성을 동적으로 관리할 때 사용되는 Chart.lock 파일을 담을 수 있어요. 의존성과 Chart.lock 파일에 대한 자세한 내용은 차트 의존성 섹션을 참고하세요.

차트 의존성

Helm에서 한 차트는 다른 차트에 얼마든지 의존할 수 있어요. 이 의존성은 Chart.yaml의 dependencies 필드를 통해 동적으로 연결되거나, 단순히 charts/ 디렉터리에 있어 수동으로 관리될 수 있어요. 동적 연결을 허용하는 최신 dependencies 필드의 경우, Helm이 의존성을 해결할 때 사용할 특정 빌드/수정/버전을 결정하는 데 사용되는 Chart.lock 파일이 생성돼요.

`dependencies` 필드로 의존성 관리

현재 권장되는 방법은 Chart.yaml의 dependencies 필드를 사용해 의존성을 선언하는 것이에요. 이 dependencies 필드는 helm dependency 명령으로 제어할 수 있어요.

dependencies 필드는 repository URL이나 alias를 추가로 지정할 수 있으며, 그 경우 단순한 dependency update를 실행할 때 nginx 차트와 함께 지정된 차트를 가져와요.

`charts/` 디렉터리로 의존성을 수동 관리

의존성을 더 수동으로 관리하고 싶다면 패키징된 차트를 charts/ 디렉터리에 그냥 복사하면 돼요. 이는 charts/ 디렉터리에 있는 패키징된 차트(패키징되어야 함)나 부모 디렉터리의 차트를 참조할 수 있음을 의미해요. 패키지를 만들 때 패키지 개발자는 설치 시점에 charts/의 차트를 이름으로 참조하거나 상대 경로로 참조할 수 있는 유연성이 있어요. 하지만 이것은 deprecated이며 개발 환경에서만 권장돼요.

하위 차트에 대한 참조는 패키지가 저장된 디렉터리 이름을 사용해요.

의존성 사용의 운영 측면

helm install 명령이 실행되면 의존성은 Helm에 의해 다음 방식으로 해결돼요:

로컬 차트를 메모리에 로드해요
Chart.yaml 의존성 필드를 읽어요
(있다면) 나열된 의존성을 완전한 차트로 해결해요
charts/ 디렉터리에서 차트 의존성을 로드해요 (있다면)
이름 충돌이 없는지 검증해요
차트와 매니페스트를 Kubernetes에 대해 검증해요

이 외에도 더 많은 단계가 있지만, 위 내용은 Helm 차트의 등록/해결 세션을 추적하고 싶다면 처리 흐름의 일반적인 개요를 제공해요.

템플릿과 값

Helm 템플릿 파일은 Sprig 및 다른 기여자의 주입이 추가된 Go 템플릿 언어로 작성돼요. Go 템플릿 언어는 강력하고 이해하기 쉬워요. Go 템플릿 언어에 대한 자세한 내용은 Go 템플릿 문서를 참고하세요.

템플릿 파일

Helm 차트는 템플릿과 구성 값으로 구성돼요. 차트의 각 리소스는 템플릿 파일로 표현돼요. 예를 들어 helm create로 만든 mychart라는 차트가 있다고 가정해요:

mychart/
  Chart.yaml
  values.yaml
  templates/
    NOTES.txt
    _helpers.tpl
    deployment.yaml
    service.yaml
    serviceaccount.yaml
    tests/test-connection.yaml

Helm은 templates/ 디렉터리의 각 템플릿 파일을 처리하고 결과를 Kubernetes로 보내요. 이 파일들은 유효한 Go 템플릿 구문으로 템플릿 처리할 수 있는 일반 텍스트 파일이에요. 값과 파일에 삽입하기 위해 {{ }} 구문을 사용하는 YAML 문서예요.

Helm은 템플릿에 특정 실행 순서를 부과하지 않으므로, 다른 템플릿에 의존하는 템플릿은 명시적으로 그렇게 설정해야 해요.

사전 정의된 값

명령줄, 값 파일 또는 부모 차트의 values.yaml을 통해 제공된 값은 Helm이 제공하는 사전 정의된 값과 대조해 사용자 제공 값(user-supplied values) 이라고 불러요. 사전 정의된 값은 어떤 템플릿에서든 접근할 수 있으며 다음을 포함해요:

Release: 릴리스가 어떻게 정의됐는지. 개별 릴리스 객체 자체가 아니라 릴리스 특정 정보를 담아요.
Values: 기본 파일인 values.yaml의 값. 차트의 병합된 값을 담아요.
Chart: Chart.yaml의 내용. 차트가 Chart.yaml을 포함한 다른 차트에 의존한다면 그 차트 데이터도 여기에서 사용할 수 있어요.
Capabilities: Kubernetes 클러스터 기능에 대한 정보를 제공해요.
Template: 현재 실행 중인 템플릿에 대한 정보(이름, 기본 경로).

Release는 다음과 같은 정보를 저장해요:

Release.Name: 릴리스 이름
Release.Namespace: 릴리스가 배포된 네임스페이스
Release.IsInstall: 설치인지 여부
Release.IsUpgrade: 업그레이드인지 여부
Release.Service: 릴리스의 현재 라이프사이클 단계
Release.Revision: 수정 번호

값 파일

값 파일은 YAML 형식으로 작성돼요. 차트는 기본 values.yaml 파일을 포함할 수 있어요. Helm CLI는 -f/--values와 -set/--set 플래그로 값 파일에 지정된 값을 재정의하는 것을 지원해요.

여러 -f 값 파일을 지정할 수 있어요. 마지막(가장 오른쪽) 파일이 다른 파일보다 우선해요.

$ helm install -f myvals.yaml ./mychart

스코프, 의존성과 값

값은 부모 차트의 values.yaml에 선언될 수 있어요. 부모 차트는 그 값에 접근할 수 있고, 하위 차트("subcharts")도 부모 차트의 values.yaml 파일에 접근할 수 있어요. 하지만 하위 차트는 다른 하위 차트의 값에는 접근할 수 없어요.

하위 차트의 values.yaml 파일은 부모 차트에서 접근할 수 없어요. 그래서 하위 차트의 values.yaml에 정의된 값은 부모로 전달될 수 없어요.

하지만 부모 차트는 하위 차트의 values.yaml 파일에 접근할 수 있어요. 차트는 하위 차트 값을 재정의할 수 있고, 부모 차트는 하위 차트의 기본값을 재정의할 수 있어요.

전역 값 (Global Values)

전역 값은 이름이 같으면 어떤 차트나 하위 차트에서든 접근할 수 있는 값이에요. 전역 값은 명시적 선언이 필요해요. values.global 밖의 임의 이름에 값을 할당해 전역 값을 암시적으로 만들 수는 없어요.

전역 값은 값 파일의 global 섹션에 값을 선언해 하위 차트에 전달할 수 있어요. 하위 차트를 정의하려면 같은 이름의 값을 참조해 global 값에 접근할 수 있어요.

마찬가지로 다른 차트나 하위 차트가 더 큰 릴리스의 일부로 설치되는지 알아야 한다면, 전역 값 Release.IsInstall에 접근해 확인할 수 있어요.

global 섹션은 필수가 아니에요. 차트의 의존성이 global 섹션에 없다면, 하위 차트 이름을 값 앞에 붙여 의존성의 값을 하위 차트에 전달할 수 있어요.

스키마 파일

스키마 파일은 JSON 스키마이며 JSON 또는 YAML로 작성돼요. 스키마 파일은 차트 값의 구조와 필드 유형을 정의해요. 스키마가 값의 전체 집합을 정의할 필요는 없지만, 설정할 수 있는 값을 제한하려면 엄격 모드(strict: true)를 설정할 수 있어요.

스키마 파일은 다음 항목을 정의해요:

차트의 값을 객체와 필드의 트리 구조로 설명해요
각 필드의 필드 유형을 정의해요
스키마에 대해 차트 값을 검증해요

스키마 값을 JSON 또는 YAML로 작성할 수 있어요. 스키마를 추가하려면 차트 루트에 schema.json / values.schema.json 파일을 추가해요.

커스텀 리소스 정의 (CRDs)

이것들은 Kubernetes 커스텀 리소스 정의예요. CRD를 포함하는 차트를 설치할 때, 그 CRD들은 다른 모든 리소스보다 먼저 클러스터에 설치돼요. CRD는 이 방식으로만 설치돼요.

CRD의 제한 사항

Kubernetes의 대부분 객체와 달리 CRD는 클러스터 범위(cluster-scoped)예요. 현재 Helm은 설치 중에 crds/ 디렉터리의 CRD만 처리하며, CRD의 생성만(업그레이드/삭제는 아님) 지원돼요. 이는 CRD에 다음 제한이 있음을 의미해요:

해당 Helm 릴리스가 업그레이드돼도 CRD는 다시 설치되지 않아요 (업그레이드는 CRD를 대체하지 않음).
해당 릴리스가 제거(uninstall)돼도 CRD는 설치되지 않아요 (삭제는 CRD를 제거하지 않음).
해당 릴리스가 갱신돼도 CRD는 갱신되지 않아요.

일반적으로 CRD는 차트 밖에서 별도의 매니페스트나 별도 도구로 처리하는 것을 권장해요.

Helm으로 차트 관리

helm create 명령은 템플릿 스타터 차트를 만들어 줘요. helm lint 명령은 설치 가능성에 대해 차트를 검증해요. helm package 명령은 차트를 버전이 붙은 아카이브로 패키징해요.

차트 저장소

차트 저장소는 하나 이상의 패키징된 차트를 담고 있는 HTTP 서버예요. Helm으로 로컬 차트 디렉터리를 관리할 수 있지만, 서버 기반 차트 저장소가 차트를 게시하는 선호되는 방식이에요. 차트 저장소에 대한 관련 문서: 차트 저장소 가이드.

차트 스타터 팩

차트 스타터 팩은 새 차트의 시작점으로 사용할 수 있는 미리 만들어진 차트예요. 스타터 팩과 그 사용법에 대한 자세한 내용은 Helm 문서에서 확인할 수 있어요.

차트

차트

본문