helm-values-management

Helm 値の管理

環境ごとの Helm 値の管理、上書きの優先順位、および高度な構成戦略に関する包括的なガイダンスです。

このスキルを使用する場面

次の場合はこのスキルを使用します…	次の場合は代わりに を使用します…
環境ごとの値ファイル（dev/staging/prod）と上書きの優先順位を設計する場合	値の構造ではなく、インストール／アップグレードコマンド自体が主な関心事である場合は、helm-release-management を使用します
--set、--set-string、--values、--reuse-values の動作を検討する場合	値のレンダリングで誤った YAML が生成される場合や、値の型エラーが発生する場合は、helm-debugging を使用します
値のスキーマ検証やシークレットの注入パターンを追加する場合	作成中のチャート内に値のスキーマがある場合は、helm-chart-development を使用します

使用する場面

次の場合は、このスキルを自動的に使用します。

• ユーザーがカスタム値で Helm デプロイを構成する必要がある
• ユーザーが環境固有の構成（dev/staging/prod）について言及している
• ユーザーが値の上書きの優先順位やマージについて質問している
• ユーザーがシークレットや機密性の高い構成を管理する必要がある
• ユーザーがデプロイされた値を確認したい
• ユーザーが値を検証または確認する必要がある

値の上書きの優先順位

値は右側優先でマージされます（最後の値が優先されます）。

1. Chart defaults (values.yaml in chart)
   ↓
2. Parent chart values (if subchart)
   ↓
3. Previous release values (--reuse-values)
   ↓
4. Values files in order (-f values1.yaml -f values2.yaml)
   ↓
5. Individual overrides (--set, --set-string, --set-json, --set-file)
   ↑
   HIGHEST PRECEDENCE

優先順位の例

# Chart values.yaml
replicaCount: 1
image:
  tag: "1.0.0"

# -f base.yaml
replicaCount: 2

# -f production.yaml
image:
  tag: "2.0.0"

# --set replicaCount=5

# RESULT:
# replicaCount: 5        (from --set, highest precedence)
# image.tag: "2.0.0"     (from production.yaml)

基本的な値のコマンド

デフォルト値の表示

# Show chart default values
helm show values <chart>

# Show values from specific chart version
helm show values <chart> --version 1.2.3

# Save defaults to file
helm show values bitnami/nginx > default-values.yaml

デプロイ済みの値の表示

# Get values used in deployed release
helm get values <release> --namespace <namespace>

# Get ALL values (including defaults)
helm get values <release> --namespace <namespace> --all

# Get values in different formats
helm get values <release> -n <namespace> -o json

# Get values from specific revision
helm get values <release> -n <namespace> --revision 2

インストール／アップグレード時の値の設定

# Using values file
helm install myapp ./chart \
  --namespace prod \
  --values values.yaml

# Using multiple values files (right-most wins)
helm install myapp ./chart \
  --namespace prod \
  -f values/base.yaml \
  -f values/production.yaml

# Using --set for individual values
helm install myapp ./chart \
  --namespace prod \
  --set replicaCount=3 \
  --set image.tag=v2.0.0

# Using --set-string to force string type
helm install myapp ./chart \
  --namespace prod \
  --set-string version="1.0"

# Using --set-json for complex structures
helm install myapp ./chart \
  --namespace prod \
  --set-json 'nodeSelector={"disktype":"ssd","region":"us-west"}'

# Using --set-file to read value from file
helm install myapp ./chart \
  --namespace prod \
  --set-file tlsCert=./certs/tls.crt

値の再利用戦略

# Reuse existing values, merge with new
helm upgrade myapp ./chart \
  --namespace prod \
  --reuse-values \
  --set image.tag=v2.0.0

# Reset to chart defaults, ignore existing values
helm upgrade myapp ./chart \
  --namespace prod \
  --reset-values \
  -f new-values.yaml

複数環境での値の管理

ディレクトリ構成

project/
├── charts/
│   └── myapp/           # Helm chart
│       ├── Chart.yaml
│       ├── values.yaml  # Chart defaults
│       └── templates/
└── values/              # Environment-specific values
    ├── common.yaml      # Shared across all environments
    ├── dev.yaml         # Development overrides
    ├── staging.yaml     # Staging overrides
    ├── production.yaml  # Production overrides
    └── secrets/         # Sensitive values (gitignored)
        ├── dev.yaml
        ├── staging.yaml
        └── production.yaml

共通値（values/common.yaml）

# Shared configuration across all environments
app:
  name: myapp
  labels:
    team: platform
    component: api

service:
  type: ClusterIP
  port: 8080

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt

resources:
  requests:
    cpu: 100m
    memory: 128Mi

デプロイコマンド

# Deploy to dev
helm upgrade --install myapp ./charts/myapp \
  --namespace dev \
  --create-namespace \
  -f values/common.yaml \
  -f values/dev.yaml \
  -f values/secrets/dev.yaml

# Deploy to staging
helm upgrade --install myapp ./charts/myapp \
  --namespace staging \
  --create-namespace \
  -f values/common.yaml \
  -f values/staging.yaml \
  -f values/secrets/staging.yaml \
  --atomic --wait

# Deploy to production
helm upgrade --install myapp ./charts/myapp \
  --namespace production \
  --create-namespace \
  -f values/common.yaml \
  -f values/production.yaml \
  -f values/secrets/production.yaml \
  --atomic --wait --timeout 10m

値の構文と型

単純な値

# String
name: myapp
tag: "v1.0.0"  # Quote to ensure string

# Number
replicaCount: 3
port: 8080

# Boolean
enabled: true
debug: false

# Null
database: null

ネストされた値

# Nested objects
image:
  repository: nginx
  tag: "1.21.0"
  pullPolicy: IfNotPresent

# Access in template: {{ .Values.image.repository }}

リスト／配列

# Simple list
tags:
  - api
  - web
  - production

# List of objects
env:
  - name: DATABASE_URL
    value: postgres://db:5432/myapp
  - name: REDIS_URL
    value: redis://cache:6379

CLI を使用した値の設定

# Simple value
--set name=myapp

# Nested value (use dot notation)
--set image.tag=v2.0.0
--set ingress.annotations."cert-manager\.io/cluster-issuer"=letsencrypt

# List values (use array index or {})
--set tags={api,web,prod}

# Complex JSON structures
--set-json 'nodeSelector={"disk":"ssd","region":"us-west"}'

# Force string (prevents numeric conversion)
--set-string version="1.0"

# Read value from file
--set-file cert=./tls.crt

値の検証とテスト

値を指定したテンプレートのレンダリング

# Render templates with values
helm template myapp ./chart --values values.yaml

# Validate against Kubernetes API
helm install myapp ./chart \
  --values values.yaml \
  --dry-run --validate

計算後の値の確認

# See what values will be used (before install)
helm template myapp ./chart \
  --values values.yaml \
  --debug 2>&1 | grep -A 100 "COMPUTED VALUES"

# See what values were used (after install)
helm get values myapp --namespace prod --all

さまざまな値の組み合わせのテスト

# Test with minimal values
helm template myapp ./chart --set image.tag=test

# Test with full production values
helm template myapp ./chart \
  -f values/common.yaml \
  -f values/production.yaml

環境ごとの値の詳しい例、スキーマ検証 JSON、シークレット管理のオプション、テンプレートでの値の処理パターン、ベストプラクティス、トラブルシューティングについては、REFERENCE.md を参照してください。

エージェント向けの最適化

コンテキスト	コマンド
値の表示（JSON）	helm get values <release> -n <ns> -o json
すべての値（JSON）	helm get values <release> -n <ns> --all -o json
計算後の値	helm template myapp ./chart -f values.yaml --debug 2>&1 | grep -A 50 "COMPUTED VALUES"
スキーマの検証	helm install myapp ./chart -f values.yaml --dry-run 2>&1 | head -50

関連スキル

• Helm Release Management - インストール／アップグレード時の値の使用
• Helm Debugging - 値のエラーのトラブルシューティング
• Helm Chart Development - 適切な値設計を備えたチャートの作成

参考資料

• Helm Values Files
• Helm Schema Validation
• Helm Secrets Plugin
• External Secrets Operator