helm-chart-builder

Helm チャートビルダー

本番環境に対応した Helm チャート。適切なデフォルト値。セキュリティを考慮した設計。盲目的な模倣はしません。

場当たり的な Kubernetes マニフェストを、保守・テスト・再利用しやすいチャートに変える、独自の方針に基づいた Helm ワークフローです。チャートの構成、値の設計、テンプレートのパターン、依存関係の管理、セキュリティ強化を扱います。

Helm のチュートリアルではありません。運用担当者から信頼され、開発者の負担にならないチャートを構築するための具体的な方針をまとめています。

---

スラッシュコマンド

コマンド	内容
/helm:create	ベストプラクティスに基づく構成で、本番環境に対応した Helm チャートのひな形を作成します
/helm:review	既存のチャートを分析し、ラベルの不足、ハードコードされた値、テンプレートのアンチパターンなどの問題を特定します
/helm:security	RBAC、ネットワークポリシー、Pod のセキュリティ、シークレットの取り扱いなど、チャートのセキュリティ上の問題を監査します

---

このスキルが有効になるとき

ユーザーから次のようなパターンを認識します。

• 「このサービスの Helm チャートを作成して」
• 「自分の Helm チャートをレビューして」
• 「このチャートは安全ですか？」
• 「values.yaml を設計して」
• 「サブチャートの依存関係を追加して」
• 「helm テストを設定して」
• 「[ワークロードの種類] における Helm のベストプラクティス」
• Helm チャート、values.yaml、Chart.yaml、templates、helpers、_helpers.tpl、サブチャート、helm lint、helm test に関するリクエスト

ユーザーが Helm チャートを持っている場合、または Kubernetes リソースをパッケージ化したい場合は、このスキルが適用されます。

---

ワークフロー

/helm:create — チャートのひな形作成

1. ワークロードの種類を特定する

   • Web サービス（Deployment + Service + Ingress）
   • ワーカー（Deployment、Service なし）
   • CronJob（CronJob + ServiceAccount）
   • ステートフルサービス（StatefulSet + PVC + Headless Service）
   • ライブラリチャート（テンプレートなし、ヘルパーのみ）

2. チャートの構成を作成する

   mychart/
   ├── Chart.yaml              # Chart metadata and dependencies
   ├── values.yaml             # Default configuration
   ├── values.schema.json      # Optional: JSON Schema for values validation
   ├── .helmignore             # Files to exclude from packaging
   ├── templates/
   │   ├── _helpers.tpl        # Named templates and helper functions
   │   ├── deployment.yaml     # Workload resource
   │   ├── service.yaml        # Service exposure
   │   ├── ingress.yaml        # Ingress (if applicable)
   │   ├── serviceaccount.yaml # ServiceAccount
   │   ├── hpa.yaml            # HorizontalPodAutoscaler
   │   ├── pdb.yaml            # PodDisruptionBudget
   │   ├── networkpolicy.yaml  # NetworkPolicy
   │   ├── configmap.yaml      # ConfigMap (if needed)
   │   ├── secret.yaml         # Secret (if needed)
   │   ├── NOTES.txt           # Post-install usage instructions
   │   └── tests/
   │       └── test-connection.yaml
   └── charts/                 # Subcharts (dependencies)
   

3. Chart.yaml にベストプラクティスを適用する

   METADATA
   ├── apiVersion: v2 (Helm 3 only — never v1)
   ├── name: matches directory name exactly
   ├── version: semver (chart version, not app version)
   ├── appVersion: application version string
   ├── description: one-line summary of what the chart deploys
   └── type: application (or library for shared helpers)
   
   DEPENDENCIES
   ├── Pin dependency versions with ~X.Y.Z (patch-level float)
   ├── Use condition field to make subcharts optional
   ├── Use alias for multiple instances of same subchart
   └── Run helm dependency update after changes
   

4. ドキュメント付きの values.yaml を生成する

   • すべての値に、目的と型を説明するインラインコメントを付けます
   • 開発環境ですぐに使える、適切なデフォルト値を設定します
   • 上書きしやすい構成にします（可能な限りフラットにし、論理的に必要な場合のみネストします）
   • クラスター固有の値（イメージレジストリ、ドメイン、ストレージクラス）をハードコードしません

5. 検証する

   python3 scripts/chart_analyzer.py mychart/
   helm lint mychart/
   helm template mychart/ --debug
   

/helm:review — チャートの分析

1. チャートの構成を確認する

   確認項目	重大度	修正方法
   _helpers.tpl がない	高	共通のラベルとセレクター用のヘルパーを作成します
   NOTES.txt がない	中	インストール後の手順を追加します
   .helmignore がない	低	.git、CI ファイル、テストを除外するファイルを作成します
   Chart.yaml のフィールドが不足している	中	description、appVersion、maintainers を追加します
   テンプレート内の値がハードコードされている	高	デフォルト値とともに values.yaml に切り出します

2. テンプレートの品質を確認する

   確認項目	重大度	修正方法
   標準ラベルがない	高	_helpers.tpl を使って app.kubernetes.io/* ラベルを設定します
   リソースのリクエスト／制限がない	重大	values.yaml にデフォルト値を設定し、resources セクションを追加します
   イメージタグがハードコードされている	高	{{ .Values.image.repository }}:{{ .Values.image.tag }} を使います
   imagePullPolicy がない	中	IfNotPresent をデフォルトにし、上書き可能にします
   liveness／readiness プローブがない	高	パスとポートを設定可能なプローブを追加します
   Pod アンチアフィニティがない	中	高可用性のために優先アンチアフィニティを追加します
   テンプレートコードが重複している	中	_helpers.tpl の名前付きテンプレートに切り出します

3. values.yaml の品質を確認する

   python3 scripts/values_validator.py mychart/values.yaml
   

4. レビューレポートを生成する

   HELM CHART REVIEW — [chart name]
   Date: [timestamp]
   
   CRITICAL: [count]
   HIGH:     [count]
   MEDIUM:   [count]
   LOW:      [count]
   
   [Detailed findings with fix recommendations]
   

/helm:security — セキュリティ監査

1. Pod のセキュリティ監査

   チェック項目	重大度	修正方法
   securityContext がない	重大	runAsNonRoot、readOnlyRootFilesystem を追加する
   root として実行している	重大	runAsNonRoot: true、runAsUser: 1000 を設定する
   ルートファイルシステムが書き込み可能	高	readOnlyRootFilesystem: true を設定し、tmp 用の emptyDir を追加する
   すべてのケイパビリティが保持されている	高	ALL を削除し、必要なものだけを追加する
   特権コンテナ	重大	privileged: false を設定し、特定のケイパビリティを使用する
   seccomp プロファイルがない	中	seccompProfile.type: RuntimeDefault を設定する
   allowPrivilegeEscalation が true	高	allowPrivilegeEscalation: false を設定する

2. RBAC 監査

   チェック項目	重大度	修正方法
   ServiceAccount がない	中	専用の SA を作成し、default を使用しない
   automountServiceAccountToken が true	中	Pod に K8s API アクセスが必要な場合を除き、false に設定する
   Role ではなく ClusterRole を使用している	中	クラスター全体での権限が必要な場合を除き、名前空間スコープの Role を使用する
   ワイルドカード権限	重大	リソース名と動詞を具体的に指定する
   RBAC がまったくない	低	Pod に K8s API アクセスが不要であれば許容可能

3. ネットワークとシークレットの監査

   チェック項目	重大度	修正方法
   NetworkPolicy がない	中	デフォルト拒否の ingress と明示的な許可ルールを追加する
   values.yaml にシークレットがある	重大	外部シークレットオペレーターまたは sealed-secrets を使用する
   PodDisruptionBudget がない	中	HA ワークロードには minAvailable を設定した PDB を追加する
   hostNetwork: true	高	絶対に必要な場合（CNI プラグインなど）を除き、削除する
   hostPID または hostIPC	重大	アプリケーションチャートでは使用しない

4. セキュリティレポートを生成する

   SECURITY AUDIT — [chart name]
   Date: [timestamp]
   
   CRITICAL: [count]
   HIGH:     [count]
   MEDIUM:   [count]
   LOW:      [count]
   
   [Detailed findings with remediation steps]
   

---

ツール

scripts/chart_analyzer.py

Helm チャートディレクトリを静的解析する CLI ユーティリティです。

機能：

• チャート構造の検証（必須ファイル、ディレクトリ構成）
• テンプレートのアンチパターン検出（ハードコードされた値、ラベルの欠落、リソース制限の欠如）
• Chart.yaml のメタデータチェック
• 標準ラベルの検証（app.kubernetes.io/*）
• セキュリティベースラインのチェック
• JSON およびテキスト形式での出力

使用方法：

# Analyze a chart directory
python3 scripts/chart_analyzer.py mychart/

# JSON output
python3 scripts/chart_analyzer.py mychart/ --output json

# Security-focused analysis
python3 scripts/chart_analyzer.py mychart/ --security

scripts/values_validator.py

values.yaml をベストプラクティスに照らして検証する CLI ユーティリティです。

機能：

• ドキュメントの網羅性（インラインコメント）
• 型の整合性チェック
• ハードコードされたシークレットの検出
• デフォルト値の品質分析
• 構造の深さの分析
• 命名規則の検証
• JSON およびテキスト形式での出力

使用方法：

# Validate values.yaml
python3 scripts/values_validator.py values.yaml

# JSON output
python3 scripts/values_validator.py values.yaml --output json

# Strict mode (fail on warnings)
python3 scripts/values_validator.py values.yaml --strict

---

テンプレートパターン

パターン 1：標準ラベル（_helpers.tpl）

{{/*
Common labels for all resources.
*/}}
{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.chart" . }}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels (subset of common labels — must be immutable).
*/}}
{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

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

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "mychart.fullname" . }}
  labels:
    {{- include "mychart.labels" . | nindent 4 }}
  {{- with .Values.ingress.annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
spec:
  {{- if .Values.ingress.tls }}
  tls:
    {{- range .Values.ingress.tls }}
    - hosts:
        {{- range .hosts }}
        - {{ . | quote }}
        {{- end }}
      secretName: {{ .secretName }}
    {{- end }}
  {{- end }}
  rules:
    {{- range .Values.ingress.hosts }}
    - host: {{ .host | quote }}
      http:
        paths:
          {{- range .paths }}
          - path: {{ .path }}
            pathType: {{ .pathType }}
            backend:
              service:
                name: {{ include "mychart.fullname" $ }}
                port:
                  number: {{ $.Values.service.port }}
          {{- end }}
    {{- end }}
{{- end }}

パターン 3：セキュリティ強化済み Pod 仕様

spec:
  serviceAccountName: {{ include "mychart.serviceAccountName" . }}
  automountServiceAccountToken: false
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 1000
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: {{ .Chart.Name }}
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop:
            - ALL
      image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
      imagePullPolicy: {{ .Values.image.pullPolicy }}
      resources:
        {{- toYaml .Values.resources | nindent 8 }}
      volumeMounts:
        - name: tmp
          mountPath: /tmp
  volumes:
    - name: tmp
      emptyDir: {}

---

Values の設計原則

STRUCTURE
├── Flat over nested (image.tag > container.spec.image.tag)
├── Group by resource (service.*, ingress.*, resources.*)
├── Use enabled: true/false for optional resources
├── Document every key with inline YAML comments
└── Provide sensible development defaults

NAMING
├── camelCase for keys (replicaCount, not replica_count)
├── Boolean keys: use adjectives (enabled, required) not verbs
├── Nested keys: max 3 levels deep
└── Match upstream conventions (image.repository, image.tag, image.pullPolicy)

ANTI-PATTERNS
├── Hardcoded cluster URLs or domains
├── Secrets as default values
├── Empty strings where null is correct
├── Deeply nested structures (>3 levels)
├── Undocumented values
└── values.yaml that doesn't work without overrides

---

依存関係の管理

SUBCHARTS
├── Use Chart.yaml dependencies (not requirements.yaml — Helm 3)
├── Pin versions: version: ~15.x.x (patch float)
├── Use condition: to make optional: condition: postgresql.enabled
├── Use alias: for multiple instances of same chart
├── Override subchart values under subchart name key in values.yaml
└── Run helm dependency update before packaging

LIBRARY CHARTS
├── type: library in Chart.yaml — no templates directory
├── Export named templates only — no rendered resources
├── Use for shared labels, annotations, security contexts
└── Version independently from application charts

---

先回りして指摘する項目

指示されなくても、以下の問題を指摘してください。

• _helpers.tpl がない → 作成します。すべてのチャートに標準ラベルと fullname ヘルパーが必要です。
• テンプレートにイメージタグがハードコードされている → values.yaml に移します。タグは上書き可能にする必要があります。
• リソースの requests/limits がない → 追加します。limits のない Pod はノードのリソースを使い果たす可能性があります。
• root として実行している → securityContext を追加します。本番用チャートに例外はありません。
• NOTES.txt がない → 作成します。ユーザーにはインストール後の手順が必要です。
• values.yaml のデフォルト値にシークレットがある → 削除します。シークレットの指定方法を説明するコメント付きのプレースホルダーを使用します。
• liveness/readiness プローブがない → 追加します。Kubernetes が Pod の健全性を確認できるようにする必要があります。
• app.kubernetes.io ラベルが不足している → _helpers.tpl を使って追加します。リソースを適切に追跡するために必要です。

---

インストール

ワンライナー（任意のツール）

git clone https://github.com/alirezarezvani/claude-skills.git
cp -r claude-skills/engineering/helm-chart-builder ~/.claude/skills/

複数ツールのインストール

./scripts/convert.sh --skill helm-chart-builder --tool codex|gemini|cursor|windsurf|openclaw

OpenClaw

clawhub install cs-helm-chart-builder

---

関連スキル

• senior-devops — より幅広い DevOps の領域（CI/CD、IaC、監視）を扱います。相互に補完的です。チャート固有の作業には helm-chart-builder を、パイプラインやインフラには senior-devops を使用します。
• docker-development — コンテナのビルドを扱います。相互に補完的です。docker-development でイメージをビルドし、helm-chart-builder で Kubernetes にデプロイします。
• ci-cd-pipeline-builder — パイプラインの構築を扱います。相互に補完的です。helm-chart-builder でデプロイ成果物を定義し、ci-cd-pipeline-builder でその配信を自動化します。
• senior-security — アプリケーションセキュリティを扱います。相互に補完的です。helm-chart-builder では Kubernetes レベルのセキュリティ（RBAC、Pod のセキュリティ）を扱い、senior-security ではアプリケーションレベルの脅威を扱います。