Helm リポジトリとドキュメントを同居させる技術──Cluster API Operator の事例紹介

背景：ドキュメントとチャートの配布先は分けるケースがある

Kubernetes 向けツールでは、ユーザーガイドと Helm チャートを別々の場所に置く構成があります。

用途	配置例
ユーザーガイド	mdBook / Hugo / Docusaurus などで生成した静的サイトを GitHub Pages へ
Helm チャート	/charts ブランチやオブジェクトストレージに index.yaml と tarball を配置

Cluster API Operator ではこれを 1 つの GitHub Pages にまとめる方式を採っています。

仕組み：鍵はルート直下の index.yaml

1. ドキュメント生成
   Markdown → mdBook で HTML を生成する。
2. チャートのメタデータをコピー
   index.yaml を、同じ公開ディレクトリ直下に置く。

Helm は index.yaml が決まった形式で配置されている URL をリポジトリとみなすため、ドキュメントサイトがそのまま Helm Repo としても振る舞います。

helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator

ブラウザからアクセスするとガイドを閲覧でき、Helm CLI からはチャートを取得できる――という形です。

補足：OCI 形式との比較

Helm チャートは HTTP リポジトリ（index.yaml 方式）のほか、OCI レジストリにプッシュする方法もあります。筆者は OCI 形式を好む立場ですが、本記事では HTTP リポジトリをドキュメントサイトと共存させる仕組み を技術的に紹介しました。目的や運用ポリシーに応じて適切な方式を選択してください。