Claude CodeでHelmチャートを設計する：values.yaml・External Secrets・staging/prod差分管理

#claudecode #kubernetes #devops #helm

はじめに

Claude CodeでKubernetesのHelmチャートを設計する際、values.yamlの環境差分管理とExternal Secrets Operatorの組み合わせが強力なパターンです。本記事では、ApplicationSetによるvalues.yamlオーバーライド、AWS SSMとの連携、--atomicロールバック、SyncWave順序制御について解説します。

CLAUDE.mdでのHelm運用ルール

## Helmチャート設計
- values.yaml: base + staging/prod オーバーライドで環境差分を管理
- External Secrets Operator: AWS SSM Parameter Store連携、平文シークレット禁止
- デプロイ: helm upgrade --install --atomic（失敗時自動ロールバック）
- ArgoCD: ApplicationSetでstagingとprodを統一管理、SyncWave順序制御

ApplicationSet + values.yaml オーバーライド構成

環境ごとのvalues.yamlを分離し、ApplicationSetで一元管理します。

# applicationset.yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp-appset
spec:
  generators:
    - list:
        elements:
          - env: staging
            replicaCount: "1"
            domain: staging.example.com
          - env: prod
            replicaCount: "3"
            domain: example.com
  template:
    spec:
      source:
        helm:
          valueFiles:
            - values.yaml
            - values-{{env}}.yaml

External Secrets Operator: AWS SSM連携

平文のシークレットをGitにコミットせず、AWS SSMからKubernetes Secretを自動生成します。

# externalsecret.yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: myapp-secrets
spec:
  refreshInterval: 5m
  secretStoreRef:
    name: aws-ssm-store
    kind: ClusterSecretStore
  target:
    name: myapp-secrets
    creationPolicy: Owner
  data:
    - secretKey: DATABASE_URL
      remoteRef:
        key: /myapp/prod/database-url
    - secretKey: API_KEY
      remoteRef:
        key: /myapp/prod/api-key

--atomic ロールバック戦略

デプロイ失敗時に自動ロールバックするため、CI/CDパイプラインでは--atomicフラグを必須とします。

helm upgrade --install myapp ./charts/myapp \
  --namespace myapp-prod \
  --values values.yaml \
  --values values-prod.yaml \
  --atomic \
  --timeout 5m \
  --wait

--atomicは--waitを暗黙的に含み、タイムアウト内にPodがReadyにならなければ自動的に前バージョンへロールバックします。

SyncWave 順序制御

ArgoCD SyncWaveを使って、データベースマイグレーションをアプリケーション起動より先に完了させます。

# migration-job.yaml
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "-1"  # アプリより先に実行

# deployment.yaml
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "0"   # マイグレーション完了後に起動