チャートリポジトリガイド

このセクションでは、Helm チャートリポジトリの作成と操作方法について説明します。大まかに言うと、チャートリポジトリとは、パッケージ化されたチャートを保存および共有できる場所です。

分散コミュニティの Helm チャートリポジトリは Artifact Hub にあり、参加を歓迎しています。しかし、Helm では独自のチャートリポジトリを作成して実行することも可能です。このガイドでは、その方法について説明します。

前提条件

クイックスタートガイドを読んでください。
チャートドキュメントを読んでください。

チャートリポジトリの作成

チャートリポジトリとは、index.yamlファイルと、オプションでいくつかのパッケージ化されたチャートを格納する HTTP サーバーです。チャートを共有する準備ができたら、チャートリポジトリにアップロードするのが推奨される方法です。

Helm 2.2.0 以降、リポジトリへのクライアント側の SSL 認証がサポートされています。その他の認証プロトコルは、プラグインとして利用できる場合があります。

チャートリポジトリは、YAML ファイルと tar ファイルを提供でき、GET リクエストに応答できる任意の HTTP サーバーにすることができるため、独自のチャートリポジトリをホストする際には、さまざまなオプションがあります。たとえば、Google Cloud Storage (GCS) バケット、Amazon S3 バケット、GitHub Pages を使用したり、独自の Web サーバーを作成したりできます。

チャートリポジトリの構造

チャートリポジトリは、パッケージ化されたチャートと、リポジトリ内のすべてのチャートのインデックスを含むindex.yamlという特別なファイルで構成されています。多くの場合、index.yamlが記述するチャートは、出自ファイルと同様に、同じサーバーでホストされます。

たとえば、リポジトリ https://example.com/charts のレイアウトは次のようになります。

charts/
  |
  |- index.yaml
  |
  |- alpine-0.1.2.tgz
  |
  |- alpine-0.1.2.tgz.prov

この場合、インデックスファイルには、Alpine チャートという1つのチャートに関する情報が含まれており、そのチャートのダウンロード URL https://example.com/charts/alpine-0.1.2.tgz が提供されます。

チャートパッケージが index.yaml ファイルと同じサーバー上にある必要はありません。ただし、そうするのが最も簡単な場合が多いです。

インデックスファイル

インデックスファイルは index.yaml という YAML ファイルです。これには、チャートの Chart.yaml ファイルの内容を含む、パッケージに関するいくつかのメタデータが含まれています。有効なチャートリポジトリにはインデックスファイルが必要です。インデックスファイルには、チャートリポジトリ内の各チャートに関する情報が含まれています。helm repo index コマンドは、パッケージ化されたチャートを含む指定されたローカルディレクトリに基づいてインデックスファイルを生成します。

これはインデックスファイルの例です。

apiVersion: v1
entries:
  alpine:
    - created: 2016-10-06T16:23:20.499814565-06:00
      description: Deploy a basic Alpine Linux pod
      digest: 99c76e403d752c84ead610644d4b1c2f2b453a74b921f422b9dcb8a7c8b559cd
      home: https://helm.dokyumento.jp/helm
      name: alpine
      sources:
      - https://github.com/helm/helm
      urls:
      - https://technosophos.github.io/tscharts/alpine-0.2.0.tgz
      version: 0.2.0
    - created: 2016-10-06T16:23:20.499543808-06:00
      description: Deploy a basic Alpine Linux pod
      digest: 515c58e5f79d8b2913a10cb400ebb6fa9c77fe813287afbacf1a0b897cd78727
      home: https://helm.dokyumento.jp/helm
      name: alpine
      sources:
      - https://github.com/helm/helm
      urls:
      - https://technosophos.github.io/tscharts/alpine-0.1.0.tgz
      version: 0.1.0
  nginx:
    - created: 2016-10-06T16:23:20.499543808-06:00
      description: Create a basic nginx HTTP server
      digest: aaff4545f79d8b2913a10cb400ebb6fa9c77fe813287afbacf1a0b897cdffffff
      home: https://helm.dokyumento.jp/helm
      name: nginx
      sources:
      - https://github.com/helm/charts
      urls:
      - https://technosophos.github.io/tscharts/nginx-1.1.0.tgz
      version: 1.1.0
generated: 2016-10-06T16:23:20.499029981-06:00

チャートリポジトリのホスティング

このパートでは、チャートリポジトリを提供するためのいくつかの方法を示します。

Google Cloud Storage

最初のステップは、GCS バケットを作成することです。ここでは fantastic-charts という名前にします。

Create a GCS Bucket

次に、バケットの権限を編集することで、バケットを公開します。

Edit Permissions

この行項目を挿入して、バケットを公開します。

Make Bucket Public

これで、チャートを提供する準備ができた空の GCS バケットができました。

Google Cloud Storage コマンドラインツールを使用するか、GCS Web UI を使用してチャートリポジトリをアップロードできます。公開された GCS バケットには、このアドレスで単純な HTTPS 経由でアクセスできます：https://bucket-name.storage.googleapis.com/。

Cloudsmith

Cloudsmith を使用してチャートリポジトリを設定することもできます。Cloudsmith でのチャートリポジトリの詳細については、こちらを参照してください。

JFrog Artifactory

同様に、JFrog Artifactory を使用してチャートリポジトリを設定することもできます。JFrog Artifactory でのチャートリポジトリの詳細については、こちらを参照してください。

GitHub Pages の例

同様に、GitHub Pages を使用してチャートリポジトリを作成できます。

GitHub では、2つの異なる方法で静的な Web ページを提供できます。

プロジェクトの docs/ ディレクトリの内容を提供するように構成する
特定のブランチを提供するようにプロジェクトを構成する

ここでは、2番目のアプローチを採用しますが、最初のアプローチも同様に簡単です。

最初のステップは、gh-pages ブランチを作成することです。これはローカルで次のように行うことができます。

$ git checkout -b gh-pages

または、GitHub リポジトリの Branch ボタンを使用して Web ブラウザ経由で行います。

次に、gh-pages ブランチが GitHub Pages として設定されていることを確認する必要があります。リポジトリの Settings をクリックし、GitHub pages セクションまでスクロールして、以下のように設定します。

Create GitHub Pages branch

デフォルトでは、通常 Source は gh-pages ブランチに設定されます。これがデフォルトで設定されていない場合は、選択してください。

必要に応じて、そこで カスタムドメインを使用できます。

そして、Enforce HTTPS がチェックされていることを確認し、チャートが提供されるときに HTTPS が使用されるようにします。

このような設定では、デフォルトブランチを使用してチャートコードを保存し、gh-pages ブランチをチャートリポジトリとして使用できます。例：https://USERNAME.github.io/REPONAME。デモンストレーション用の TS Charts リポジトリには、https://technosophos.github.io/tscharts/ からアクセスできます。

GitHub pages を使用してチャートリポジトリをホストすることにした場合は、Chart Releaser Action をチェックしてください。Chart Releaser Action は、GitHub プロジェクトを helm/chart-releaser CLI ツールを使用して、セルフホスト型の Helm チャートリポジトリに変えるための GitHub Action ワークフローです。

通常の Web サーバー

通常の Web サーバーを構成して Helm チャートを提供する場合は、次のことを行うだけで済みます。

サーバーが提供できるディレクトリにインデックスとチャートを配置する
index.yaml ファイルに認証要件なしでアクセスできることを確認する
yaml ファイルが正しいコンテンツタイプ (text/yaml または text/x-yaml) で提供されることを確認する

たとえば、$WEBROOT/charts からチャートを提供したい場合は、Web ルートに charts/ ディレクトリがあることを確認し、そのフォルダー内にインデックスファイルとチャートを配置します。

ChartMuseum リポジトリサーバー

ChartMuseum は、Go (Golang) で記述されたオープンソースの Helm チャートリポジトリサーバーであり、Google Cloud Storage、Amazon S3、Microsoft Azure Blob Storage、Alibaba Cloud OSS Storage、Openstack Object Storage、Oracle Cloud Infrastructure Object Storage、Baidu Cloud BOS Storage、Tencent Cloud Object Storage、DigitalOcean Spaces、Minio、および etcd を含む、クラウドストレージバックエンドのサポートを備えています。

ChartMuseum サーバーを使用して、ローカルファイルシステムからチャートリポジトリをホストすることもできます。

GitLab パッケージレジストリ

GitLab を使用すると、プロジェクトのパッケージレジストリに Helm チャートを公開できます。GitLab での Helm パッケージリポジトリの設定の詳細については、こちらを参照してください。

チャートリポジトリの管理

これでチャートリポジトリができたので、このガイドの最後の部分では、そのリポジトリでチャートをどのように管理するかを説明します。

チャートリポジトリにチャートを保存する

チャートリポジトリができたので、チャートとインデックスファイルをリポジトリにアップロードしましょう。チャートリポジトリ内のチャートは、パッケージ化（helm package chart-name/）され、正しくバージョン管理（SemVer 2ガイドラインに従って）されている必要があります。

以下の手順はワークフローの例を構成するものですが、チャートをチャートリポジトリに保存および更新するために、好きなワークフローを使用しても構いません。

パッケージ化されたチャートの準備ができたら、新しいディレクトリを作成し、パッケージ化されたチャートをそのディレクトリに移動します。

$ helm package docs/examples/alpine/
$ mkdir fantastic-charts
$ mv alpine-0.1.0.tgz fantastic-charts/
$ helm repo index fantastic-charts --url https://fantastic-charts.storage.googleapis.com

最後のコマンドは、作成したローカルディレクトリのパスとリモートチャートリポジトリのURLを取得し、指定されたディレクトリパス内にindex.yamlファイルを作成します。

これで、同期ツールを使用するか、手動で、チャートとインデックスファイルをチャートリポジトリにアップロードできます。Google Cloud Storageを使用している場合は、gsutilクライアントを使用したこのワークフローの例を確認してください。GitHubの場合は、チャートを適切な宛先ブランチに配置するだけです。

既存のリポジトリに新しいチャートを追加する

リポジトリに新しいチャートを追加するたびに、インデックスを再生成する必要があります。helm repo indexコマンドは、ローカルで見つかったチャートのみを含め、index.yamlファイルを完全に最初から再構築します。

ただし、--mergeフラグを使用して、既存のindex.yamlファイルに新しいチャートを段階的に追加することができます（GCSのようなリモートリポジトリを使用する場合に最適なオプションです）。詳細については、helm repo index --helpを実行してください。

必ず、修正したindex.yamlファイルとチャートの両方をアップロードしてください。また、来歴ファイルを生成した場合は、それもアップロードしてください。

チャートを共有する準備ができたら、リポジトリのURLを誰かに知らせるだけです。

そこから、彼らはhelm repo add [NAME] [URL]コマンドを使用して、リポジトリを参照するために使用したい任意の名前で、リポジトリをhelmクライアントに追加します。

$ helm repo add fantastic-charts https://fantastic-charts.storage.googleapis.com
$ helm repo list
fantastic-charts    https://fantastic-charts.storage.googleapis.com

チャートがHTTP基本認証で保護されている場合は、ここでユーザー名とパスワードを指定することもできます。

$ helm repo add fantastic-charts https://fantastic-charts.storage.googleapis.com --username my-username --password my-password
$ helm repo list
fantastic-charts    https://fantastic-charts.storage.googleapis.com

注：有効なindex.yamlが含まれていない場合、リポジトリは追加されません。

注：Helmリポジトリが例えば自己署名証明書を使用している場合は、CA検証をスキップするためにhelm repo add --insecure-skip-tls-verify ...を使用できます。

その後、ユーザーはチャートを検索できるようになります。リポジトリを更新した後、helm repo updateコマンドを使用して、最新のチャート情報を取得できます。

内部的には、helm repo addコマンドとhelm repo updateコマンドは、index.yamlファイルを取得し、$XDG_CACHE_HOME/helm/repository/cache/ディレクトリに保存します。これが、helm search関数がチャートに関する情報を見つける場所です。