Helm 차트 설계 Best Practices: 네이밍, Values 설계, GitOps 통합

# _helpers.tpl의 fullname은 릴리스 이름 + 차트 이름 조합
# 63자 제한을 반드시 준수
{{- define "my-chart.fullname" -}}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}

# templates/_helpers.tpl
{{- define "my-chart.labels" -}}
app.kubernetes.io/name: {{ include "my-chart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/component: "backend"
app.kubernetes.io/part-of: "my-platform"
app.kubernetes.io/managed-by: {{ .Release.Service }}
helm.sh/chart: {{ include "my-chart.chart" . }}
{{- end }}

# Flat 구조 - 단순하지만 관련 설정 그룹화 어려움
imageRepository: nginx
imageTag: '1.25'
imagePullPolicy: IfNotPresent

# Nested 구조 - 권장
image:
  repository: nginx
  tag: '1.25'
  pullPolicy: IfNotPresent

# values.yaml - 합리적인 기본값 제공
replicaCount: 1

image:
  repository: nginx
  tag: '' # 비어있으면 Chart.appVersion 사용
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

ingress:
  enabled: false
  className: ''
  annotations: {}
  hosts: []
  tls: []

# 빈 객체/리스트로 확장 포인트 제공
podAnnotations: {}
podLabels: {}
nodeSelector: {}
tolerations: []
affinity: {}
extraEnvVars: []
extraVolumes: []
extraVolumeMounts: []

# 필수값은 required 함수로 강제
image: {{ required "image.repository is required" .Values.image.repository }}

# 선택적 값은 default로 안전하게 처리
tag: {{ .Values.image.tag | default .Chart.AppVersion }}

# 복잡한 기본값 로직
{{- if .Values.persistence.existingClaim }}
claimName: {{ .Values.persistence.existingClaim }}
{{- else }}
claimName: {{ include "my-chart.fullname" . }}-data
{{- end }}

values.yaml              # 기본값 (차트에 포함)
values-common.yaml       # 공통 오버라이드
values-dev.yaml          # 개발 환경
values-staging.yaml      # 스테이징 환경
values-production.yaml   # 프로덕션 환경

# 환경별 배포
helm upgrade --install my-app ./my-chart \
  -f values-common.yaml \
  -f values-production.yaml \
  --set image.tag=v2.1.0

# values-production.yaml
replicaCount: 3

image:
  pullPolicy: Always

resources:
  limits:
    cpu: '2'
    memory: 2Gi
  requests:
    cpu: 500m
    memory: 512Mi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  targetCPUUtilizationPercentage: 70

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: app-tls
      hosts:
        - app.example.com

podDisruptionBudget:
  enabled: true
  minAvailable: 2

my-platform/
  Chart.yaml
  values.yaml
  charts/
    frontend/
    backend-api/
    worker/

# Chart.yaml
apiVersion: v2
name: my-platform
version: 1.0.0
type: application
dependencies:
  - name: frontend
    version: '2.x.x'
    repository: 'file://charts/frontend'
  - name: backend-api
    version: '3.x.x'
    repository: 'file://charts/backend-api'
  - name: redis
    version: '17.x.x'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: redis.enabled
  - name: postgresql
    version: '12.x.x'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: postgresql.enabled

# ArgoCD Application
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/helm-charts
    targetRevision: main
    path: charts/my-app
    helm:
      releaseName: my-app
      valueFiles:
        - values.yaml
        - values-production.yaml
      parameters:
        - name: image.tag
          value: 'v2.1.0'
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

# Flux HelmRelease
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: my-app
  namespace: production
spec:
  interval: 10m
  chart:
    spec:
      chart: my-app
      version: '>=1.0.0'
      sourceRef:
        kind: HelmRepository
        name: my-charts
        namespace: flux-system
  values:
    replicaCount: 3
    image:
      repository: myregistry/my-app
      tag: v2.1.0
  valuesFrom:
    - kind: ConfigMap
      name: my-app-values
      valuesKey: production.yaml
  upgrade:
    remediation:
      retries: 3
  rollback:
    timeout: 5m

gitops-repo/
  apps/
    my-app/
      base/
        kustomization.yaml
        helmrelease.yaml
      overlays/
        dev/
          kustomization.yaml
          values.yaml
        staging/
          kustomization.yaml
          values.yaml
        production/
          kustomization.yaml
          values.yaml

# 나쁜 예: latest 태그 사용
image:
  tag: latest

# 좋은 예: 불변(immutable) 태그 또는 다이제스트 사용
image:
  tag: "v2.1.0"
  # 또는 다이제스트
  # digest: sha256:abc123...

# 나쁜 예: values에 시크릿 평문 저장
database:
  password: 'my-secret-password'

# 좋은 예: 외부 시크릿 참조
# helm-secrets, External Secrets Operator, Sealed Secrets 사용
externalSecret:
  enabled: true
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore

# values.schema.json에서 resources 필수화
{
  'required': ['resources'],
  'properties': { 'resources': { 'type': 'object', 'required': ['limits', 'requests'] } },
}

# values.yaml 기본값
podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000
  seccompProfile:
    type: RuntimeDefault

containerSecurityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities:
    drop:
      - ALL

# Chart.yaml annotations
annotations:
  artifacthub.io/changes: |
    - kind: added
      description: Add HPA support
    - kind: changed
      description: Update default resource limits
    - kind: fixed
      description: Fix ingress TLS configuration

# values.yaml에서 deprecated 값 처리
{{- if .Values.oldConfig }}
  {{- fail "oldConfig is deprecated. Use newConfig instead." }}
{{- end }}

# 또는 경고 메시지 출력
{{- if .Values.oldConfig }}
  {{- printf "WARNING: oldConfig is deprecated and will be removed in v3.0. Use newConfig instead." | fail }}
{{- end }}