Helm 레이블과 어노테이션

1 개요[ | ]

Helm Chart에서 레이블(label)과 어노테이션(annotation)은 모두 쿠버네티스 오브젝트의 metadata 필드에 정의된다. 두 속성은 용도와 쓰임새가 다르므로, 모범 사례에 따라 올바르게 구분하는 것이 중요하다.

다음 조건을 만족하면 레이블(label)로 지정한다:

예: helm.sh/chart: NAME-VERSION → 특정 차트 버전으로 배포된 모든 리소스를 찾을 때 사용 가능.

쿼리에 활용하지 않는 메타데이터는 어노테이션(annotation)으로 지정한다.

Helm 훅(Hook)은 항상 어노테이션으로 정의해야 한다.

Helm 자체는 특정 레이블을 강제하지 않지만, 차트 간 일관성을 위해 권장되는 레이블 세트가 존재한다. 상태(Status)는 REC(recommended, 권장) 또는 OPT(optional, 선택적)으로 구분된다.

이름	상태	설명
`app.kubernetes.io/name`	REC	앱 이름 전체를 반영한다. 보통 `{{ template "name" . }}` 사용. Kubernetes 전반에서 널리 쓰이며 Helm 전용은 아님.
`helm.sh/chart`	REC	차트 이름과 버전을 지정한다. `{{ .Chart.Name }}-{{ .Chart.Version \| replace "+" "_" }}`
`app.kubernetes.io/managed-by`	REC	항상 `{{ .Release.Service }}` 로 지정한다. Helm이 관리하는 리소스를 식별할 때 사용.
`app.kubernetes.io/instance`	REC	`{{ .Release.Name }}` 으로 지정한다. 동일 앱의 여러 인스턴스를 구분하는 데 유용.
`app.kubernetes.io/version`	OPT	앱 버전을 지정한다. `{{ .Chart.AppVersion }}` 활용.
`app.kubernetes.io/component`	OPT	앱 내 역할(컴포넌트)을 나타낸다. 예: `frontend`, `database`.
`app.kubernetes.io/part-of`	OPT	상위 애플리케이션을 지정한다. 예: 웹사이트를 구성하는 앱과 DB 조합.