Helm Chart Scaffolding

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: devops@example.com
    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. テンプレートファイルを作成する

Goテンプレート機能を使用したHelmテンプレート：

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'

関連スキル

• k8s-manifest-generator - ベースのKubernetesマニフェスト作成用
• gitops-workflow - Helmチャートの自動デプロイメント用