k8s-helm
Use when modifying Helm charts (Chart.yaml, templates/*.tpl, values*.yaml) to enforce chart structure, values override hierarchy, helper template patterns. Skip when kustomize is the deployment tool.
SKILL.mdassets/skills/kubernetes/k8s-helm/SKILL.md
GitHubHelm Best Practices
Helm chart 개발 패턴 및 best practices.
Chart Structure
charts/myapp/
├── Chart.yaml # Chart metadata
├── values.yaml # Default values
├── values-dev.yaml # Dev overrides
├── values-prod.yaml # Prod overrides
├── templates/
│ ├── _helpers.tpl # Template helpers
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── configmap.yaml
│ ├── secret.yaml
│ ├── ingress.yaml
│ └── NOTES.txt # Post-install notes
└── README.md
Chart.yaml
apiVersion: v2
name: myapp
description: A Helm chart for MyApp
type: application
version: 0.1.0 # Chart version (SemVer)
appVersion: "1.2.3" # Application version
values.yaml Template
# Image configuration
image:
repository: myregistry/myapp
tag: "v1.2.3"
pullPolicy: IfNotPresent
# Resource limits
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "256Mi"
cpu: "250m"
# Replica count
replicaCount: 2
# Service configuration
service:
type: ClusterIP
port: 80
# Ingress configuration
ingress:
enabled: false
className: nginx
hosts: []
# Security context
podSecurityContext:
runAsNonRoot: true
runAsUser: 1000
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop:
- ALL
# Probes
livenessProbe:
httpGet:
path: /healthz
port: http
initialDelaySeconds: 15
periodSeconds: 10
readinessProbe:
httpGet:
path: /ready
port: http
initialDelaySeconds: 5
periodSeconds: 5
Template Helpers (_helpers.tpl)
{{/*
Expand the name of the chart.
*/}}
{{- define "myapp.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}
{{/*
Create a default fully qualified app name.
*/}}
{{- define "myapp.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{/*
Common labels
*/}}
{{- define "myapp.labels" -}}
helm.sh/chart: {{ include "myapp.chart" . }}
{{ include "myapp.selectorLabels" . }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}
Deployment Template
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "myapp.fullname" . }}
labels:
{{- include "myapp.labels" . | nindent 4 }}
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels:
{{- include "myapp.selectorLabels" . | nindent 6 }}
template:
metadata:
labels:
{{- include "myapp.selectorLabels" . | nindent 8 }}
spec:
securityContext:
{{- toYaml .Values.podSecurityContext | nindent 8 }}
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
securityContext:
{{- toYaml .Values.securityContext | nindent 12 }}
resources:
{{- toYaml .Values.resources | nindent 12 }}
{{- with .Values.livenessProbe }}
livenessProbe:
{{- toYaml . | nindent 12 }}
{{- end }}
Library Chart 패턴
Library vs Application Chart
# Library Chart: type: library (직접 설치 불가, 공통 템플릿 제공)
# charts/common-lib/Chart.yaml
apiVersion: v2
name: common-lib
type: library # ← 핵심 차이
version: 0.1.0
# Application Chart: type: application (기본값, 설치 가능)
# charts/example-server/Chart.yaml
apiVersion: v2
name: example-server
type: application
dependencies:
- name: common-lib
version: "0.1.x"
repository: "file://../common-lib" # 로컬 참조
공통 템플릿 정의 → include 호출
# Library Chart: charts/common-lib/templates/_deployment.tpl
{{- define "common-lib.deployment" -}}
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "common-lib.fullname" . }}
labels: {{- include "common-lib.labels" . | nindent 4 }}
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels: {{- include "common-lib.selectorLabels" . | nindent 6 }}
template:
metadata:
labels: {{- include "common-lib.selectorLabels" . | nindent 8 }}
spec:
serviceAccountName: {{ include "common-lib.serviceAccountName" . }}
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
{{- with .Values.resources }}
resources: {{- toYaml . | nindent 10 }}
{{- end }}
{{- end }}
# Application Chart: charts/example-server/templates/deployment.yaml
{{- include "common-lib.deployment" . }}
MSA 확장 구조
charts/
├── common-lib/ # Library Chart (공통 템플릿)
│ ├── Chart.yaml # type: library
│ └── templates/
│ ├── _deployment.tpl
│ ├── _service.tpl
│ ├── _gateway.tpl
│ ├── _serviceaccount.tpl
│ ├── _hpa.tpl
│ └── _pdb.tpl
├── example-server/ # Application Chart
│ ├── Chart.yaml # depends on common-lib
│ ├── values.yaml
│ └── templates/
│ └── deployment.yaml # {{ include "common-lib.deployment" . }}
└── example-payment/ # 새 서비스도 같은 Library Chart 활용
├── Chart.yaml
└── ...
ArgoCD 환경에서 Helm의 역할
역할 분리
ArgoCD가 하는 것:
1. helm template → 매니페스트 렌더링
2. kubectl apply → 클러스터에 적용
3. 릴리즈 관리 (Sync, Rollback, Health)
Helm이 하는 것:
1. 템플릿 엔진 (Go template)
2. 패키징 (Chart archive)
3. 의존성 관리 (Chart.yaml dependencies)
ArgoCD가 하지 않는 것:
✗ helm install / helm upgrade ← 직접 실행 안 함
✗ Helm Release 객체 생성 ← Tiller/Secret 기반 릴리즈 없음
✗ Helm Hook 트리거 ← ArgoCD Hook으로 교체 필수
Helm Hook → ArgoCD Hook 교체
ArgoCD는 helm template만 실행하므로 helm.sh/hook은 무시됨.
반드시 argocd.argoproj.io/hook으로 교체. 상세: /gitops-argocd-helm
values.schema.json
{
"$schema": "https://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["image", "replicaCount"],
"properties": {
"image": {
"type": "object",
"required": ["repository", "tag"],
"properties": {
"repository": { "type": "string" },
"tag": { "type": "string", "pattern": "^v?[0-9]" }
}
},
"replicaCount": { "type": "integer", "minimum": 1 }
}
}
helm lint시 자동 검증, CI에서helm lint --strict활용- 필수 값 누락 즉시 감지, 잘못된 타입(문자열 대신 숫자 등) 방지
YAML Anchor / Alias
Kind, ArgoCD, Helm values 모두 표준 Go YAML 파서 사용 → anchor/alias 정상 지원.
# Kind 클러스터 설정 예시: 이미지 반복 제거
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
image: &nodeImage kindest/node:v1.32.0 # anchor 정의
- role: worker
image: *nodeImage # alias 참조
- role: worker
image: *nodeImage
# Helm values: 공통 설정 재사용
defaults: &defaults
resources:
requests: { cpu: "100m", memory: "128Mi" }
limits: { cpu: "200m", memory: "256Mi" }
server:
<<: *defaults # merge key로 defaults 병합
replicaCount: 2
worker:
<<: *defaults
replicaCount: 4
멀티 환경 Values 관리
디렉토리 기반 구조
environments/
├── dev/
│ ├── example-server/values.yaml # dev 전용 override
│ └── monitoring/values.yaml
├── staging/
│ └── example-server/values.yaml
└── prod/
└── example-server/values.yaml
charts/
└── example-server/
└── values.yaml # 기본값 (모든 환경 공통)
ApplicationSet + Multi-source $values/ 패턴
sources:
- repoURL: https://github.com/myorg/k8s-config.git
chart: example-server
targetRevision: "1.0.0"
helm:
valueFiles:
- $values/environments/dev/example-server/values.yaml
- repoURL: https://github.com/myorg/k8s-config.git
targetRevision: main
ref: values # $values로 참조
원칙
- 기본값은
charts/{service}/values.yaml에 정의 - 환경별 override만
environments/{env}/{service}/values.yaml에 작성 - 기본값을 환경별 파일에 중복 정의하지 않음 (override만)
Validation Commands
# Lint chart (schema 포함)
helm lint charts/myapp/ --strict
# Template rendering
helm template myapp charts/myapp/ -f values-prod.yaml
# Dry run install
helm install myapp charts/myapp/ --dry-run --debug
# Validate with kubeval
helm template myapp charts/myapp/ | kubeval
Anti-patterns
| Mistake | Correct | Why |
|---|---|---|
| Hardcoded values in templates | Use values.yaml | Configurability |
| No default values | Provide sensible defaults | Usability |
| Long template names | Use _helpers.tpl | DRY principle |
| Missing NOTES.txt | Add post-install info | User guidance |
| No resource limits | Always set limits | Cluster stability |
ArgoCD 환경에서 helm upgrade 직접 실행 |
ArgoCD Sync 사용 | 릴리즈 상태 충돌, drift 발생 |
| "YAML anchor 미지원" 확인 없이 단정 | 공식 문서 확인 후 판단 | Go YAML 파서는 anchor/alias 지원 |
| 환경별 values에 기본값 중복 정의 | override만 작성 | 변경 시 동기화 누락 위험 |
관련 skill: /docker, /k8s-security, /gitops-argocd-helm