Helm 아키텍처 내부 분석: Helm 3의 설계 철학과 구조

+------------------+       +---------------------+
|   Helm CLI       | ----> |  Kubernetes API     |
|  (클라이언트)     |       |  Server             |
+------------------+       +---------------------+
        |                           |
        v                           v
  +-----------+              +-----------+
  | Chart     |              | Release   |
  | Repository|              | Storage   |
  +-----------+              | (Secrets) |
                             +-----------+

# Helm 3는 kubeconfig의 컨텍스트를 그대로 사용
# RBAC이 자연스럽게 적용됨
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: helm-deployer
  namespace: production
rules:
  - apiGroups: ['', 'apps', 'batch']
    resources: ['deployments', 'services', 'configmaps', 'secrets']
    verbs: ['get', 'list', 'create', 'update', 'patch', 'delete']

# 릴리스 Secret 조회
kubectl get secrets -l owner=helm -n default

# Secret 이름 형식: sh.helm.release.v1.RELEASE_NAME.vREVISION
# 예: sh.helm.release.v1.my-app.v1

# ConfigMap 드라이버 사용
export HELM_DRIVER=configmap
helm install my-app ./my-chart

my-chart/
  Chart.yaml          # 차트 메타데이터 (필수)
  Chart.lock          # 의존성 잠금 파일
  values.yaml         # 기본 설정값 (필수)
  values.schema.json  # values 스키마 검증
  charts/             # 의존성 차트 (서브차트)
  crds/               # CRD 매니페스트
  templates/          # Go 템플릿 파일
    deployment.yaml
    service.yaml
    ingress.yaml
    _helpers.tpl      # 네임드 템플릿 헬퍼
    NOTES.txt         # 릴리스 노트 템플릿
    tests/            # 테스트 Pod 정의
      test-connection.yaml

apiVersion: v2 # Helm 3에서는 반드시 v2
name: my-application
description: A Helm chart for my application
type: application # application 또는 library
version: 1.2.3 # 차트 버전 (SemVer)
appVersion: '2.0.0' # 애플리케이션 버전
kubeVersion: '>=1.25.0' # 지원 Kubernetes 버전 범위
home: https://example.com
sources:
  - https://github.com/example/my-app
maintainers:
  - name: developer
    email: dev@example.com
icon: https://example.com/icon.png
keywords:
  - app
  - web
annotations:
  artifacthub.io/changes: |
    - kind: added
      description: Initial release
dependencies:
  - name: postgresql
    version: '12.x.x'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: postgresql.enabled
    tags:
      - database

# crds/my-crd.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.example.com
spec:
  group: example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
  scope: Namespaced
  names:
    plural: myresources
    singular: myresource
    kind: MyResource

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: { { include "my-chart.fullname" . } }
  labels: { { - include "my-chart.labels" . | nindent 4 } }
spec:
  replicas: { { .Values.replicaCount } }
  selector:
    matchLabels: { { - include "my-chart.selectorLabels" . | nindent 6 } }
  template:
    metadata:
      labels: { { - include "my-chart.selectorLabels" . | nindent 8 } }
    spec:
      containers:
        - name: { { .Chart.Name } }
          image: '{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}'
          ports:
            - containerPort: { { .Values.service.port } }

# .Release 객체 활용 예시
metadata:
  annotations:
    helm.sh/release-name: {{ .Release.Name }}
    helm.sh/release-namespace: {{ .Release.Namespace }}
    helm.sh/revision: {{ .Release.Revision | quote }}

# .Capabilities 활용 예시
{{- if .Capabilities.APIVersions.Has "networking.k8s.io/v1" }}
apiVersion: networking.k8s.io/v1
{{- else }}
apiVersion: networking.k8s.io/v1beta1
{{- end }}

# 문자열 함수
name: {{ .Values.name | upper }}           # 대문자 변환
name: {{ .Values.name | lower }}           # 소문자 변환
name: {{ .Values.name | title }}           # 타이틀 케이스
name: {{ .Values.name | trim }}            # 공백 제거
name: {{ .Values.name | trunc 63 }}        # 63자로 자르기

# 기본값 설정
image: {{ .Values.image.tag | default "latest" }}

# 조건부 필수값
name: {{ required "A name is required" .Values.name }}

# 인코딩
data: {{ .Values.secret | b64enc }}

# 날짜
timestamp: {{ now | date "2006-01-02T15:04:05Z07:00" }}

# Chart.yaml
dependencies:
  - name: redis
    version: '17.x.x'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: redis.enabled
    tags:
      - cache
  - name: postgresql
    version: '12.x.x'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: postgresql.enabled
    tags:
      - database
  - name: common
    version: '2.x.x'
    repository: 'https://charts.bitnami.com/bitnami'
    import-values:
      - child: image
        parent: defaultImage

# 의존성 다운로드 및 잠금 파일 생성
helm dependency update ./my-chart

# Chart.lock이 이미 있는 경우 정확한 버전으로 빌드
helm dependency build ./my-chart

# Chart.lock
dependencies:
  - name: redis
    repository: https://charts.bitnami.com/bitnami
    version: 17.15.2
  - name: postgresql
    repository: https://charts.bitnami.com/bitnami
    version: 12.10.0
digest: sha256:abc123def456...
generated: '2026-03-20T10:00:00.000000000Z'

# values.yaml
redis:
  enabled: true
postgresql:
  enabled: false # PostgreSQL 서브차트 비활성화

# values.yaml
tags:
  cache: true # cache 태그가 붙은 모든 의존성 활성화
  database: false # database 태그가 붙은 모든 의존성 비활성화

# 부모 차트의 values.yaml에서 서브차트 값 오버라이드
redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: false
  master:
    persistence:
      size: 1Gi

postgresql:
  enabled: true
  auth:
    postgresPassword: 'my-password'
    database: mydb

# values.yaml
global:
  imageRegistry: myregistry.io
  imagePullSecrets:
    - name: my-pull-secret
  storageClass: fast-ssd

# 레지스트리 로그인
helm registry login registry.example.com

# 차트를 OCI 아티팩트로 패키징 및 푸시
helm package ./my-chart
helm push my-chart-1.0.0.tgz oci://registry.example.com/charts

# OCI 레지스트리에서 차트 설치
helm install my-release oci://registry.example.com/charts/my-chart --version 1.0.0

# 차트 정보 조회
helm show chart oci://registry.example.com/charts/my-chart --version 1.0.0