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
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

# 依存関係のダウンロードとロックファイルの生成
helm dependency update ./my-chart

# 既存のChart.lockから正確なバージョンでビルド
helm dependency build ./my-chart

# values.yaml
redis:
  enabled: true
postgresql:
  enabled: false # PostgreSQLサブチャートを無効化

# values.yaml
tags:
  cache: true # cacheタグのすべての依存関係を有効化
  database: false # databaseタグのすべての依存関係を無効化

# 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