helm-generator

Helm チャートジェネレーター

概要

決定論的なスキャフォールディング、標準ヘルパー、再利用可能なテンプレート、検証ループを備えた、本番環境ですぐに使える Helm チャートを生成します。

公式ドキュメント：

• Helm ドキュメント - メインドキュメント
• チャートのベストプラクティス - 公式ベストプラクティスガイド
• テンプレート関数 - 組み込み関数
• Sprig 関数 - 拡張関数ライブラリ

このスキルを使う場面

helm-generator を使う	その他のスキルを使う
新しい Helm チャートを作成する	helm-validator：既存のチャートを検証／lint する
Helm テンプレートを生成する	k8s-yaml-generator：生の K8s YAML（Helm なし）
K8s マニフェストを Helm に変換する	k8s-debug：デプロイ済みリソースをデバッグする
Helm で CRD を実装する	k8s-yaml-validator：K8s マニフェストを検証する

トリガーフレーズ

プロンプトに次のようなフレーズが含まれている場合、このスキルを使います。

• 「Helm チャートを作成」
• 「Helm チャートをスキャフォールディング」
• 「Helm テンプレートを生成」
• 「マニフェストを Helm チャートに変換」
• 「Deployment／Service／Ingress を含むチャートを構築」

実行フロー

以下のステージを順番に実行します。必須のステージを省略しないでください。

ステージ 1：要件の収集（必須）

以下を収集します。

• スコープ：チャート全体、特定のテンプレート、またはマニフェストからの変換
• ワークロード：deployment、statefulset、または daemonset
• イメージ参照：リポジトリ、任意のタグ、またはダイジェスト
• ポート：サービスのポートとコンテナーのターゲットポート（それぞれ別の値）
• ランタイム設定：リソース、プローブ、自動スケーリング、Ingress、ストレージ
• セキュリティ：サービスアカウント、セキュリティコンテキスト、任意の RBAC／ネットワークポリシー

重要な項目が不足している場合は、request_user_input を使います。

request_user_input を使えない場合は、通常のチャットで質問し、明示的な前提条件を示して続行します。

不足している情報	質問
イメージのリポジトリ／タグ	「使用するコンテナーイメージは何ですか？（例：nginx:1.25）」
サービスポート	「公開するサービスポートはいくつですか？」
コンテナーのターゲットポート	「トラフィックを転送するコンテナーポートはいくつですか？」
リソース制限	「CPU／メモリーの制限はいくつにしますか？（例：CPU 500m、メモリー 512Mi）」
プローブのエンドポイント	「アプリが公開するヘルスチェックのエンドポイントは何ですか？（例：/health、/ready）」
スケーリング要件	「自動スケーリングを有効にしますか？有効にする場合、レプリカの最小数／最大数と目標 CPU 使用率は何％ですか？」
ワークロードの種類	「ワークロードの種類は何ですか？Deployment、StatefulSet、DaemonSet のいずれですか？」
ストレージ要件	「アプリケーションに永続ストレージは必要ですか？必要な場合、サイズとアクセスモードを教えてください。」

重要な設定を黙って仮定しないでください。

ステージ 2：CRD ドキュメントの参照（CRD が対象に含まれる場合のみ）

1. まず Context7 を試します。
   • mcp__context7__resolve-library-id
   • mcp__context7__query-docs
2. Context7 を利用できない場合、または情報が不十分な場合のフォールバック順：
   • Operator の公式ドキュメント（優先）
   • 一般的なウェブ検索

例のパターンについては、references/crd_patterns.md も参照してください。

ステージ 3：チャート構造のスキャフォールドを作成する（必須）

実行：

bash scripts/generate_chart_structure.sh <chart-name> <output-directory> [options]

オプション：

• --image <repo> - リポジトリのみ、タグ付きイメージ、レジストリポート、ダイジェスト参照に対応します
• --port <number> - サービスポート（デフォルト：80）
• --target-port <number> - コンテナーのターゲットポート（デフォルト：8080）
• --type <type> - ワークロードの種類：deployment、statefulset、daemonset（デフォルト：deployment）
• --with-templates - リソーステンプレート（deployment.yaml、service.yaml など）を生成します
• --with-ingress - Ingress テンプレートを含めます
• --with-hpa - HPA テンプレートを含めます
• --force - 確認を求めずに既存のチャートを上書きします

イメージの解析動作：

• --image nginx:1.27 -> リポジトリ nginx、タグ 1.27
• --image registry.local:5000/team/app -> リポジトリをそのまま保持します
• --image ghcr.io/org/app@sha256:... -> ダイジェストモード（タグを連結しません）
• --tag はダイジェストイメージ参照と併用できません

冪等性と上書きの動作：

• generate_chart_structure.sh：上書き前に確認します。--force を指定すると、確認なしで上書きします。
• generate_standard_helpers.sh：templates/_helpers.tpl の置き換え前に確認します。--force を指定すると確認を省略します。

スキャフォールドの想定構成：

mychart/
  Chart.yaml
  values.yaml
  templates/
    _helpers.tpl
    NOTES.txt
    serviceaccount.yaml
    service.yaml
    configmap.yaml
    secret.yaml
    deployment.yaml|statefulset.yaml|daemonset.yaml
    ingress.yaml (optional)
    hpa.yaml (optional)
  .helmignore

ステージ 4：標準ヘルパーを生成する

実行：

bash scripts/generate_standard_helpers.sh <chart-name> <chart-directory>

必須ヘルパー：name、fullname、chart、labels、selectorLabels、serviceAccountName。

代替手順：

• スクリプトの実行がブロックされた場合は、assets/_helpers-template.tpl をコピーし、CHARTNAME をチャート名に置き換えます。

ステージ 5：リファレンスを確認してテンプレートを生成する（必須）

このステージでは、関連するリファレンスを一度確認します：

• 生成するリソースパターンについては references/resource_templates.md
• テンプレート関数の使用方法については references/helm_template_functions.md
• CRD が対象となる場合に限り references/crd_patterns.md

ファイルを開くコマンドの例：

sed -n '1,220p' references/resource_templates.md
sed -n '1,220p' references/helm_template_functions.md

references/resource_templates.md に記載されているリソースの範囲：

• ワークロード：Deployment、StatefulSet、DaemonSet、Job、CronJob
• サービス：Service、Ingress
• 設定：ConfigMap、Secret
• RBAC：ServiceAccount、Role、RoleBinding、ClusterRole、ClusterRoleBinding
• ネットワーク：NetworkPolicy
• オートスケーリング：HPA、PodDisruptionBudget

必須のテンプレートパターン：

metadata:
  name: {{ include "mychart.fullname" . }}
  labels: {{- include "mychart.labels" . | nindent 4 }}

{{- with .Values.nodeSelector }}
nodeSelector: {{- toYaml . | nindent 2 }}
{{- end }}

annotations:
  {{- if and .Values.configMap .Values.configMap.enabled }}
  checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
  {{- end }}

ワークロードにはチェックサムアノテーションが必須ですが、条件付きでのみ指定し、生成されたテンプレート（configmap.yaml、secret.yaml）だけを参照する必要があります。

ステージ 6：values.yaml を作成する

構成のガイドライン：

• 関連する設定を論理的にまとめます
• すべての値に # -- コメントで説明を付けます
• 適切なデフォルト値を設定します
• セキュリティコンテキスト、リソース制限、プローブを含めます
• service.port と service.targetPort は分けて明示します
• configMap.enabled / secret.enabled を生成されたテンプレートに合わせます

JSON Schema による検証については、assets/values-schema-template.json を参照してください。

ステージ 7：検証する

推奨手順：helm-validator スキルを実行します。

スキルを呼び出せない場合は、ローカルコマンドを直接実行します：

helm lint <chart-dir>
helm template test <chart-dir>

helm を利用できない場合は、阻害要因を明確に報告し、部分的なチェックを実施します：

• bash -n scripts/generate_chart_structure.sh
• bash -n scripts/generate_standard_helpers.sh
• 生成されたファイルと主要なフィールドを手動で確認します

修正後は検証を再実行します。

テンプレート関数クイックリファレンス

完全なガイドについては references/helm_template_functions.md を参照してください。

関数	用途	例
required	必須の値を適用する	{{ required "msg" .Values.x }}
default	フォールバック値	{{ .Values.x | default 1 }}
quote	文字列を引用符で囲む	{{ .Values.x | quote }}
include	ヘルパーを使用する	{{ include "name" . | nindent 4 }}
toYaml	YAML に変換する	{{ toYaml .Values.x | nindent 2 }}
tpl	テンプレートとしてレンダリングする	{{ tpl .Values.config . }}
nindent	改行してインデントする	{{- include "x" . | nindent 4 }}

CRD の操作

完全な例については、references/crd_patterns.md を参照してください。

主なポイント：

• 同梱する CRD -> crds/ ディレクトリ（テンプレート化されず、アンインストール時にも削除されません）
• CR インスタンス -> templates/ ディレクトリ（完全にテンプレート化されます）
• CRD の仕様要件に関するドキュメントを必ず確認してください
• Chart.yaml のアノテーションにオペレーターの依存関係を記載してください

マニフェストを Helm に変換する

1. パラメーター化： 名前 -> ヘルパー、値 -> values.yaml
2. パターンを適用： ラベル、条件分岐、複雑なオブジェクトには toYaml
3. ヘルパーを追加： 標準ヘルパーを含む _helpers.tpl を作成します
4. 検証： helm-validator（またはローカルの lint/template フォールバック）を実行し、異なる値でテストします

エラー処理

問題	解決策
テンプレート構文エラー	helm template test <chart-dir> --debug --show-only templates/<file>.yaml
未定義の値	helm lint <chart-dir> --strict を実行し、default／required を追加します
チェックサムの include エラー	templates/configmap.yaml と templates/secret.yaml が存在し、configMap.enabled／secret.enabled が正しく設定されていることを確認します
ポートの不一致（Service とコンテナ間）	service.port と service.targetPort の両方を設定し、helm template test <chart-dir> を再実行します
CRD の検証失敗	Context7 またはオペレーターのドキュメントで apiVersion／spec フィールドを確認し、再レンダリングします
スクリプト引数のエラー	bash scripts/generate_chart_structure.sh --help を実行し、オプションフラグに必要な値を渡します

使用例

テンプレート、ingress、HPA、明示的なポートマッピングを含む完全なスキャフォールド：

bash scripts/generate_chart_structure.sh webapp ./charts \
  --image ghcr.io/acme/webapp:2.3.1 \
  --port 80 \
  --target-port 8080 \
  --type deployment \
  --with-templates \
  --with-ingress \
  --with-hpa

ダイジェストベースのイメージスキャフォールド：

bash scripts/generate_chart_structure.sh api ./charts \
  --image ghcr.io/acme/api@sha256:0123456789abcdef \
  --with-templates

テンプレートを含まない最小限のスキャフォールド：

bash scripts/generate_chart_structure.sh starter ./charts

スキャフォールドの成功基準

すべてのチェックに合格した場合にのみ完了とします：

• Chart.yaml、values.yaml、.helmignore、templates/NOTES.txt、および templates/_helpers.tpl が存在する
• values.yaml に明示的な service.port と service.targetPort が含まれている
• --with-templates を使用した場合、serviceaccount.yaml、service.yaml、configmap.yaml、secret.yaml、およびワークロードテンプレートが 1 つ存在する
• 生成されたワークロードテンプレートで、config／secret 用の条件付きチェックサムアノテーションが使用されている
• イメージのレンダリングロジックがタグモードとダイジェストモードに対応している
• 検証が完了し（helm-validator スキルまたはローカルのフォールバックコマンド）、結果が報告されている

リソース

スクリプト

スクリプト	使用方法
scripts/generate_chart_structure.sh	bash scripts/generate_chart_structure.sh <chart-name> <output-dir> [options]
scripts/generate_standard_helpers.sh	bash scripts/generate_standard_helpers.sh <chart-name> <chart-dir> [--force]

参照資料

ファイル	内容
references/helm_template_functions.md	テンプレート関数の完全ガイド
references/resource_templates.md	すべての K8s リソーステンプレート
references/crd_patterns.md	CRD パターン（cert-manager、Prometheus、Istio、ArgoCD）

アセット

ファイル	用途
assets/_helpers-template.tpl	標準ヘルパーテンプレート
assets/values-schema-template.json	値の検証用 JSON Schema

helm-validator との連携

チャートを生成した後、helm-validator を実行して最後まで対応します：

1. チャート／テンプレートを生成します
2. helm-validator（またはローカルのフォールバックコマンド）を実行します
3. 特定された問題を修正します
4. 合格するまで再検証します