helm-chart-development

Helm チャートの開発

保守性と再利用性に関するベストプラクティスに沿って、カスタム Helm チャートを作成、テスト、パッケージ化するための包括的なガイダンスです。

このスキルを使用するタイミング

次の場合にこのスキルを使用します...	次の場合は を使用します...
helm create、Chart.yaml、テンプレート、依存関係を使って新しいチャートを作成する場合	既存のチャートをインストールまたはアップグレードする場合は helm-release-management を使用します
独自のチャートをリント、パッケージ化、公開する場合	環境間で値をオーバーライドする場合は helm-values-management を使用します
チャートのテストを追加したり、テンプレートの構造を改善したりする場合	既存のデプロイに失敗している場合や、テンプレートが正しくレンダリングされない場合は helm-debugging を使用します

使用するタイミング

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

• ユーザーが新しい Helm チャートを作成したい
• ユーザーがチャートの構造やテンプレートを検証する必要がある
• ユーザーがチャートをローカルでテストすることに言及している
• ユーザーがチャートをパッケージ化または公開したい
• ユーザーがチャートの依存関係を管理する必要がある
• ユーザーがチャートのベストプラクティスについて質問している

チャートの作成と構造

新しいチャートの作成

# Scaffold new chart with standard structure
helm create mychart

# Creates:
# mychart/
# ├── Chart.yaml          # Chart metadata
# ├── values.yaml         # Default values
# ├── charts/             # Chart dependencies
# ├── templates/          # Kubernetes manifests
# │   ├── NOTES.txt       # Post-install instructions
# │   ├── _helpers.tpl    # Template helpers
# │   ├── deployment.yaml
# │   ├── service.yaml
# │   ├── ingress.yaml
# │   └── tests/
# │       └── test-connection.yaml
# └── .helmignore         # Files to ignore

Chart.yaml の構造

# Chart.yaml - Chart metadata
apiVersion: v2                  # Helm 3 uses v2
name: mychart                   # Chart name
version: 0.1.0                  # Chart version (SemVer)
appVersion: "1.0.0"            # Application version
description: A Helm chart for Kubernetes
type: application               # application or library
keywords:
  - api
  - web
home: https://example.com
sources:
  - https://github.com/example/mychart
maintainers:
  - name: John Doe
    email: [email protected]
dependencies:                   # Chart dependencies
  - name: postgresql
    version: "12.1.9"
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled  # Optional: enable/disable
    tags:                          # Optional: group dependencies
      - database

チャートの検証とテスト

チャートのリント

# Basic linting
helm lint ./mychart

# Strict linting (warnings as errors)
helm lint ./mychart --strict

# Lint with specific values
helm lint ./mychart --values values.yaml --strict

# Lint with multiple value files
helm lint ./mychart \
  --values values/common.yaml \
  --values values/production.yaml \
  --strict

テンプレートをローカルでレンダリングする

# Render all templates
helm template mychart ./mychart

# Render with custom release name and namespace
helm template myrelease ./mychart --namespace production

# Render with values
helm template myrelease ./mychart --values values.yaml

# Render specific template
helm template myrelease ./mychart \
  --show-only templates/deployment.yaml

# Validate against Kubernetes API
helm template myrelease ./mychart --validate

ドライランでインストールする

# Dry-run with server-side validation
helm install myrelease ./mychart \
  --namespace production \
  --dry-run \
  --debug

チャートのテストを実行する

# Install chart, run tests, cleanup
helm install myrelease ./mychart --namespace test
helm test myrelease --namespace test --logs
helm uninstall myrelease --namespace test

チャートテストの構造：

# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "mychart.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
    "helm.sh/hook-delete-policy": hook-succeeded,hook-failed
spec:
  containers:
  - name: wget
    image: busybox
    command: ['wget']
    args: ['{{ include "mychart.fullname" . }}:{{ .Values.service.port }}']
  restartPolicy: Never

テンプレートの開発

テンプレートヘルパー（_helpers.tpl）

{{/*
Expand the name of the chart.
*/}}
{{- define "mychart.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create a fully qualified app name.
*/}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{/*
Common labels
*/}}
{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.chart" . }}
{{ include "mychart.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels
*/}}
{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

チャートの依存関係

依存関係を定義する（Chart.yaml）

# Chart.yaml
dependencies:
- name: postgresql
  version: "12.1.9"
  repository: https://charts.bitnami.com/bitnami
  condition: postgresql.enabled

- name: redis
  version: "17.0.0"
  repository: https://charts.bitnami.com/bitnami
  condition: redis.enabled

- name: common                         # Local dependency
  version: "1.0.0"
  repository: file://../common-library

依存関係を管理する

# Download/update dependencies
helm dependency update ./mychart

# Build from existing Chart.lock
helm dependency build ./mychart

# List dependencies
helm dependency list ./mychart

サブチャートの値を設定する

# values.yaml - Parent chart
postgresql:
  enabled: true
  auth:
    username: myapp
    database: myapp
    existingSecret: myapp-db-secret
  primary:
    persistence:
      size: 10Gi

redis:
  enabled: true
  auth:
    enabled: false
  master:
    persistence:
      size: 5Gi

チャートのパッケージ化と配布

チャートをパッケージ化する

# Package chart into .tgz
helm package ./mychart

# Package with specific destination
helm package ./mychart --destination ./dist/

# Package and update dependencies
helm package ./mychart --dependency-update

# Sign package (requires GPG key)
helm package ./mychart --sign --key mykey --keyring ~/.gnupg/secring.gpg

チャートリポジトリ

# Create repository index
helm repo index ./repo/

# Push to OCI registry (Helm 3.8+)
helm push mychart-0.1.0.tgz oci://registry.example.com/charts

values.yaml の設計、スキーマ検証、チャートドキュメントのテンプレート、テストワークフロー、一般的なチャートパターン、ベストプラクティスに関する詳細な例については、REFERENCE.md を参照してください。

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

コンテキスト	コマンド
リント（厳格）	helm lint ./mychart --strict
特定のテンプレートをレンダリング	helm template myapp ./mychart --show-only templates/deployment.yaml
ドライランでの検証	helm install myapp ./mychart --dry-run --debug 2>&1 | head -100
チャートをパッケージ化	helm package ./mychart --dependency-update

関連スキル

• Helm リリース管理 - チャートを使ったデプロイ
• Helm デバッグ - チャートの問題のトラブルシューティング
• Helm 値の管理 - チャートの設定

参考資料

• Helm チャート開発ガイド
• Helm ベストプラクティス
• Helm テンプレートガイド
• チャートのテスト