Claude CodeでHelmチャートを作成する手順

Claude Codeにhelm createの骨格を実装させると、テンプレートの記述とvalues.yamlの設計を一度に進められます。この記事では、チャートの骨格作成からテンプレート実装、values.yamlの設計、helm lint/templateによる検証までを手順化します。

Claude CodeでHelmチャートを作るとはどんな作業か

Helmチャートは、Kubernetesにデプロイする一連のリソースをテンプレート化したパッケージです。Chart.yaml(メタデータ)・values.yaml(デフォルト値)・templates/(テンプレート本体)の3点を軸に構成し、values.yamlの値をテンプレートに埋め込んでKubernetesのマニフェストを生成します。

Claude CodeでHelmチャートを書く作業は、ほかの言語のコードを書かせる作業と同じ通常のコーディング支援です。精度を左右するのは、対象リソースの種類・外部から上書きしたい値・既存の命名規則を、どれだけ具体的に伝えるかです。

Kubernetesクラスタ自体をClaudeから直接操作したい場合は、チャートを書く作業とは別の選択肢としてKubernetes MCPサーバーでClaudeからクラスタを操作するという手段もあります。同記事のMCPサーバーはHelmチャートの操作にも対応しますが、ここで扱うのはチャート自体を書く作業です。

前提条件

Helmチャートの雛形生成にはHelm CLIのインストールが必要です。Macではbrew install helm、その他の環境は公式のインストールガイドに従います。

brew install helm

helm templateはクラスタに接続せずにレンダリングできますが、実際にhelm installまで進める場合はクラスタへの接続とkubectlの設定が必要です。まずはクラスタなしで書き進め、最後にインストールで確認する進め方がこの記事の流れです。

手順1: helm createで骨格を作り、Claude Codeにテンプレートを実装させる

最初にhelm createでチャートの骨格を作ります。指定した名前のディレクトリにChart.yaml・values.yaml・charts/・templates/・templates/tests/・.helmignoreが生成されます。

helm create mychart

公式チュートリアルは、生成直後のmychart/templates/にあるNOTES.txt(インストール後に表示するヘルプテキスト)・deployment.yaml(Deploymentの基本マニフェスト)・service.yaml(Serviceのマニフェスト)・_helpers.tpl(テンプレート間で再利用するヘルパー)の4つを挙げています。Helm公式のチュートリアルは、ゼロから書く練習のためにこれらを一度削除します。ただし日々のチャート作成では、全部消す必要はないとも書いています。基本形として残して編集する進め方が現実的です。

Claude Codeにテンプレートの実装を依頼するときは、対象リソースの種類と、どの値を外部から変えられるようにしたいかを伝えます。

ConfigMapのテンプレートを追加して。データキーはfavoriteDrinkで、値はvalues.yamlから読み込むようにして

たとえば次のような形になります(Helm公式チュートリアルのConfigMap例と同じ構成)。

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-configmap
data:
  favoriteDrink: {{ .Values.favoriteDrink | quote }}

{{ .Release.Name }}はHelmの組み込みオブジェクトで、helm install時に指定したリリース名がそのまま入ります。同様に{{ .Chart.Name }}-{{ .Chart.Version }}と書けばChart.yamlに書いたチャート名とバージョンが展開されます。ReleaseオブジェクトにはRelease.Namespace(デプロイ先の名前空間)・Release.IsUpgrade(アップグレードまたはロールバックの実行時にtrue)・Release.IsInstall(新規インストール時にtrue)といったフィールドもあり、条件分岐が必要なテンプレートではこれらを使って処理を切り替えられます。

複数のテンプレートで同じラベルやリソース名の組み立てを繰り返す場合は、その組み立てロジックを_helpers.tplに1つ定義し、各テンプレートからincludeで呼び出すよう指示すると、命名規則がテンプレート間でずれません。Claude Codeに複数リソースを書かせるときは、「ラベルの組み立てを_helpers.tplに集約して」と条件を添えるのが有効です。

Chart.yamlの必須フィールドはapiVersion・name・versionの3つで、descriptionや対応するkubeVersion(SemVer範囲)は任意です。Claude CodeにChart.yamlを書かせる際も、この3つが埋まっているかを確認します。

手順2: values.yamlの設計をClaude Codeに任せる

values.yamlの構造は、テンプレート側の参照方法や後からの上書き方法まで左右します。公式のベストプラクティスに沿って条件を伝えると、Claude Codeが生成する構造も安定します。

命名規則: 変数名は小文字始まりのキャメルケースにします(chickenNoodleSoupのように)。ハイフンを含む名前や先頭大文字の名前は避けます。Helmの組み込み変数(Release.Nameなど)はすべて大文字始まりなので、ユーザー定義値と衝突しません。

文字列は明示的にクオートする: YAMLの型変換は直感に反する場合があります。foo: falseとfoo: "false"は別の値になり、foo: 12345678のような大きな整数は指数表記に変換されることもあります。文字列は明示的にクオートし、それ以外は暗黙の型に任せる、という原則がもっとも安全です。

values.yamlの値は-fで渡すファイルだけでなく、--setオプションでも上書きされます。配列(リスト)は--set servers[0].port=80のようにインデックス指定が必要になり扱いにくいため、キーで指定できるマップ構造の方が上書きしやすくなります。

必要に応じてvalues.schema.jsonを置くと、values.yamlの構造をJSON Schemaで強制できます。任意のファイルですが、Claude Codeに複数人で使うチャートを書かせる場合は、スキーマ生成もあわせて依頼すると値の取り違えを防げます。

手順3: helm lintとtemplateでチャートを検証する

テンプレートとvalues.yamlを書いたら、まずhelm lintとhelm templateの2つのコマンドで確認します。

helm lintは、インストールに失敗する不備があれば[ERROR]、規約や推奨から外れる程度の問題は[WARNING]として報告します。

helm lint mychart

helm templateはクラスタから本来取得する値をローカルでダミー値に置き換えてレンダリングするだけで、対応するAPIが実際にクラスタ側に存在するかまでは検証しません。生成されるYAML自体を目で確認したいときに使います。

helm template mychart

インストールせずに生成マニフェストだけを確認したい場合は、helm installに--debugと--dry-runを組み合わせます。--dry-run=clientはクラスタに接続せずクライアント側だけで検証し、--dry-run=serverはクラスタに接続してAPIサーバー側の検証まで行います。--dry-runはSecretsの内容も含めて出力するため、機密情報が混ざる場合は--hide-secretを併用します。

helm install mychart ./mychart --debug --dry-run=server

helm lintは[WARNING]だけなら失敗扱いにならないので、CIなどで警告も止めたいときは--strict(lintの警告で失敗させるオプション)を付けます。--setや-fで値を渡せるため、本番用のvaluesファイルを当てた状態でも検査できます。

IsUpgradeやAPI有無の分岐をクラスタなしで再現する

テンプレートにRelease.IsUpgradeやCapabilitiesの分岐があると、helm templateの既定のレンダリングでは片側しか見えません。helm templateには、この分岐を切り替えるフラグがあります。

helm template mychart ./mychart --is-upgrade --show-only templates/configmap.yaml

--show-onlyは指定したテンプレートの描画結果だけを表示します。helm templateは、APIがクラスタに存在するかというサーバー側の検査をしません。そのため--api-versionsで渡した値は、テンプレート内の条件分岐を通すためのものです。

一連のファイル一式が整い、検証も通ったら、変更をコミットしてPRを作る作業もClaude Codeに任せられます。手順はClaude CodeでPRを作成する手順にまとめています。

手順4: lintとtemplateをClaude Code自身に反復実行させる

手順3の2コマンドは、Claude Codeに手元で打たせることもできます。Bashツールでコマンドを実行できる状態であれば、helm lintとhelm templateをClaude Code自身に実行させ、出力された[ERROR]や[WARNING]、レンダリング結果を読ませて該当箇所を直させる、という反復に持ち込めます。

mychartに対してhelm lintとhelm templateを実行して、出たERRORとWARNINGを直して。直したら両方をもう一度実行して確認して

こうした指示を出せば、helm lintの[ERROR]・[WARNING]を読んで該当するテンプレートやvalues.yamlを直し、再度lintとtemplateを実行して確認するところまでを一度の依頼で任せられます。人がコマンドを1つずつ打ち、出力をコピーして渡す手間を省けます。

このやり取りを何度も繰り返すなら、helm lintとhelm templateの実行確認を毎回省く設定も有効です。プロジェクトの.claude/settings.jsonのpermissions.allowに次の2行を加えると、以後この2コマンドは確認なしで実行されます。

{
  "permissions": {
    "allow": [
      "Bash(helm lint *)",
      "Bash(helm template *)"
    ]
  }
}

*はサブコマンドより後ろに置くのが安全です。Bash(helm *)と書くとhelm installやhelm uninstallまで含めて全許可になってしまうため、検証用の2コマンドだけを許可するなら上記のようにlint・templateの後ろに*を置きます。

ルールの当たり方には3つの癖があります。

• Bash(helm lint *)は引数なしのhelm lintにも当たります。*の前の空白がルールの一部で、helm lintxのような別名には当たりません。
• helm --debug lint mychartのように、サブコマンドの前にフラグを置いた形はhelm lint *に当たりません。
• helm lint mychart && helm template mychartのような複合コマンドは、&&で分けた各部分が別々にルールへ照合されます。2行とも許可していれば通ります。

ルールは引数の中身を見ないため、helm template mychart --output-dir ./outのようなファイルを書き出す呼び出しも同じ許可に含まれます。一度きりの許可なら、Claude Code v2.1.289のclaude --helpにある--allowedTools(カンマか空白区切りでツール名を並べる)に"Bash(helm lint *)" "Bash(helm template *)"を渡す方法もあります。

命名規則やvalues.yamlの構造方針(フラット優先・キャメルケースの命名・文字列の明示クオート)も、都度の指示に書く代わりにプロジェクトのCLAUDE.mdに一度書いておくと、以後Claude Codeに新しいテンプレートを書かせるときにその条件を省けます。CLAUDE.mdはビルドコマンドやコーディング規約のように「セッションをまたいで常に守ってほしいこと」を書く場所で、チャートの命名・values設計方針もこれに当たります。

よくあるつまずき

Release.IsUpgradeをアップグレード専用のフィールドだと思い込むと落とし穴になります。helm upgradeだけでなくhelm rollbackの実行時にもtrueになるためです。ロールバックの分岐が必要なテンプレートでRelease.IsUpgradeだけで判定すると、ロールバック時の処理も一緒に走ります。--is-upgradeで描画して、想定した側が出るかを確かめます。

Chart.yamlのkubeVersionは任意項目なので、書かないままでもチャート自体は作れます。ただし対応するKubernetesのバージョン範囲を指定しておかないと、非対応のクラスタへ気づかずインストールしてしまう余地が残ります。対応させたいバージョン範囲が決まっているなら、Claude Codeに書かせる際にその範囲を伝え、kubeVersionを埋めるよう条件を添えます。

まとめ

Helmチャートは、骨格をhelm createで作ってからClaude Codeに実装させると、命名とvaluesの設計を公式の指針に揃えやすくなります。検証はhelm lintと、クラスタに繋がずに描画できるhelm templateをClaude Code自身に繰り返させ、分岐の描画は--is-upgradeなどのフラグで確かめます。クラスタ側の適合性だけが--dry-run=serverの担当です。作ったチャートを本番へ上げる前の差分レビューは、helm diffのアップグレード前差分をレビューする手順で扱っています。