helm-chart-scaffolding

Helm チャートのスキャフォールディング

Kubernetes アプリケーションをパッケージ化してデプロイするための Helm チャートの作成、整理、管理に関する包括的なガイダンスです。

目的

このスキルでは、チャートの構造、テンプレートのパターン、値の管理、検証戦略など、本番環境ですぐに使える Helm チャートを構築するための手順を説明します。

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

次のような場合に、このスキルを使用してください。

• Helm チャートを一から新規作成する
• Kubernetes アプリケーションを配布用にパッケージ化する
• Helm を使用して複数環境へのデプロイを管理する
• 再利用可能な Kubernetes マニフェスト向けにテンプレートを実装する
• Helm チャートリポジトリを設定する
• Helm のベストプラクティスと規約に従う

Helm の概要

Helm は Kubernetes 用のパッケージマネージャーで、次の機能を提供します。

• Kubernetes マニフェストをテンプレート化して再利用可能にする
• アプリケーションのリリースとロールバックを管理する
• チャート間の依存関係を処理する
• デプロイにバージョン管理を提供する
• 環境間の構成管理を簡素化する

ステップごとのワークフロー

1. チャート構造を初期化する

新しいチャートを作成する：

helm create my-app

標準的なチャート構造：

my-app/
├── Chart.yaml           # Chart metadata
├── values.yaml          # Default configuration values
├── charts/              # Chart dependencies
├── templates/           # Kubernetes manifest templates
│   ├── NOTES.txt       # Post-install notes
│   ├── _helpers.tpl    # Template helpers
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── serviceaccount.yaml
│   ├── hpa.yaml
│   └── tests/
│       └── test-connection.yaml
└── .helmignore         # Files to ignore

2. Chart.yaml を設定する

チャートのメタデータでパッケージを定義します：

apiVersion: v2
name: my-app
description: A Helm chart for My Application
type: application
version: 1.0.0 # Chart version
appVersion: '2.1.0' # Application version

# Keywords for chart discovery
keywords:
  - web
  - api
  - backend

# Maintainer information
maintainers:
  - name: DevOps Team
    email: [email protected]
    url: https://github.com/example/my-app

# Source code repository
sources:
  - https://github.com/example/my-app

# Homepage
home: https://example.com

# Chart icon
icon: https://example.com/icon.png

# Dependencies
dependencies:
  - name: postgresql
    version: '12.0.0'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: postgresql.enabled
  - name: redis
    version: '17.0.0'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: redis.enabled

参照： 完全な例については assets/Chart.yaml.template を参照してください。

3. values.yaml の構造を設計する

値を階層的に整理します：

# Image configuration
image:
  repository: myapp
  tag: '1.0.0'
  pullPolicy: IfNotPresent

# Number of replicas
replicaCount: 3

# Service configuration
service:
  type: ClusterIP
  port: 80
  targetPort: 8080

# Ingress configuration
ingress:
  enabled: false
  className: nginx
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix

# Resources
resources:
  requests:
    memory: '256Mi'
    cpu: '250m'
  limits:
    memory: '512Mi'
    cpu: '500m'

# Autoscaling
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

# Environment variables
env:
  - name: LOG_LEVEL
    value: 'info'

# ConfigMap data
configMap:
  data:
    APP_MODE: production

# Dependencies
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp

redis:
  enabled: false

参照： 完全な構造については assets/values.yaml.template を参照してください。

4. テンプレートファイルを作成する

Helm の関数を使用して Go テンプレートを記述します：

templates/deployment.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-app.fullname" . }}
  labels:
    {{- include "my-app.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "my-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "my-app.selectorLabels" . | nindent 8 }}
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
        ports:
        - name: http
          containerPort: {{ .Values.service.targetPort }}
        resources:
          {{- toYaml .Values.resources | nindent 12 }}
        env:
          {{- toYaml .Values.env | nindent 12 }}

5. テンプレートヘルパーを作成する

templates/_helpers.tpl：

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

{{/*
Create a default fully qualified app name.
*/}}
{{- define "my-app.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 "my-app.labels" -}}
helm.sh/chart: {{ include "my-app.chart" . }}
{{ include "my-app.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

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

6. 依存関係を管理する

Chart.yaml に依存関係を追加します：

dependencies:
  - name: postgresql
    version: '12.0.0'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: postgresql.enabled

依存関係を更新します：

helm dependency update
helm dependency build

依存関係の値をオーバーライドします：

# values.yaml
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp
    password: changeme
  primary:
    persistence:
      enabled: true
      size: 10Gi

7. テストと検証を行う

検証コマンド：

# Lint the chart
helm lint my-app/

# Dry-run installation
helm install my-app ./my-app --dry-run --debug

# Template rendering
helm template my-app ./my-app

# Template with values
helm template my-app ./my-app -f values-prod.yaml

# Show computed values
helm show values ./my-app

検証スクリプト：

#!/bin/bash
set -e

echo "Linting chart..."
helm lint .

echo "Testing template rendering..."
helm template test-release . --dry-run

echo "Checking for required values..."
helm template test-release . --validate

echo "All validations passed!"

参照： scripts/validate-chart.sh を参照してください。

8. パッケージ化して配布する

チャートをパッケージ化します：

helm package my-app/
# Creates: my-app-1.0.0.tgz

チャートリポジトリを作成します：

# Create index
helm repo index .

# Upload to repository
# AWS S3 example
aws s3 sync . s3://my-helm-charts/ --exclude "*" --include "*.tgz" --include "index.yaml"

チャートを使用します：

helm repo add my-repo https://charts.example.com
helm repo update
helm install my-app my-repo/my-app

9. 複数環境向けの構成

環境固有の値ファイル：

my-app/
├── values.yaml          # Defaults
├── values-dev.yaml      # Development
├── values-staging.yaml  # Staging
└── values-prod.yaml     # Production

values-prod.yaml：

replicaCount: 5

image:
  tag: '2.1.0'

resources:
  requests:
    memory: '512Mi'
    cpu: '500m'
  limits:
    memory: '1Gi'
    cpu: '1000m'

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20

ingress:
  enabled: true
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix

postgresql:
  enabled: true
  primary:
    persistence:
      size: 100Gi

環境を指定してインストールします：

helm install my-app ./my-app -f values-prod.yaml --namespace production

10. フックとテストを実装する

インストール前フック：

# templates/pre-install-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "my-app.fullname" . }}-db-setup
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: db-setup
        image: postgres:15
        command: ["psql", "-c", "CREATE DATABASE myapp"]
      restartPolicy: Never

接続をテストします：

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

テストを実行します：

helm test my-app

よくあるパターン

パターン 1：条件付きリソース

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "my-app.fullname" . }}
spec:
  # ...
{{- end }}

パターン 2：リストの反復処理

env:
{{- range .Values.env }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

パターン 3：ファイルのインクルード

data:
  config.yaml: |
    {{- .Files.Get "config/application.yaml" | nindent 4 }}

パターン 4：グローバル値

global:
  imageRegistry: docker.io
  imagePullSecrets:
    - name: regcred

# Use in templates:
image: {{ .Values.global.imageRegistry }}/{{ .Values.image.repository }}

ベストプラクティス

1. チャートとアプリのバージョンにはセマンティックバージョニングを使用する
2. values.yaml のすべての値をコメントで説明する
3. 繰り返し使うロジックにはテンプレートヘルパーを使用する
4. パッケージ化する前にチャートを検証する
5. 依存関係のバージョンを明示的に固定する
6. オプションのリソースには条件を使用する
7. 命名規則（小文字、ハイフン）に従う
8. 使用方法を記載した NOTES.txt を含める
9. ヘルパーを使用してラベルを一貫して追加する
10. すべての環境でインストールをテストする

トラブルシューティング

テンプレートのレンダリングエラー：

helm template my-app ./my-app --debug

依存関係の問題：

helm dependency update
helm dependency list

インストールの失敗：

helm install my-app ./my-app --dry-run --debug
kubectl get events --sort-by='.lastTimestamp'

参照ファイル

• assets/Chart.yaml.template - チャートのメタデータテンプレート
• assets/values.yaml.template - 値の構造テンプレート
• scripts/validate-chart.sh - 検証スクリプト
• references/chart-structure.md - チャート構成の詳細

関連スキル

• k8s-manifest-generator - Kubernetes のベースマニフェストを作成する場合
• gitops-workflow - Helm チャートのデプロイを自動化する場合

メモリプロトコル（必須）

開始前：

cat C:\dev\projects\agent-studio\.claude\context\memory\learnings.md

完了後：

• 新しいパターン -> C:\dev\projects\agent-studio\.claude\context\memory\learnings.md
• 問題の発見 -> C:\dev\projects\agent-studio\.claude\context\memory\issues.md
• 決定事項 -> C:\dev\projects\agent-studio\.claude\context\memory\decisions.md

中断が発生することを前提にしてください。メモリに記録されていなければ、実行されていないものとみなされます。