次の方法で共有

Azure コンテナー レジストリに対する Helm グラフのプッシュおよびプル

  • [アーティクル]

アプリケーションを Kubernetes 用に簡単に管理し、デプロイするには、オープン ソースの Helm パッケージ マネージャーを使用します。 Helm を使用すると、アプリケーション パッケージはグラフとして定義されます。これは収集され、Helm グラフ リポジトリに格納されます。

この記事では、Helm 3 のコマンドを使用し、グラフを OCI 成果物として格納して、Azure コンテナー レジストリで Helm グラフ リポジトリをホストする方法について説明します。 多くのシナリオでは、開発したアプリケーション用の独自のグラフを構築し、アップロードすることになります。 独自の Helm グラフを作成する方法の詳細については、「Chart Template Developer's Guide (グラフ テンプレート開発者ガイド)」を参照してください。 また、別の Helm リポジトリから既存の Helm グラフを格納することもできます。

Note

この記事は、Helm 3 コマンドで更新されました。 Helm 3.7 には、以前のバージョンの Helm 3 で導入された、Helm CLI コマンドと OCI サポートへの変更が含まれています。 設計上、helm はバージョンの更新と共に進歩します。 3.7.2 以降を使用することをお勧めします。

重要

  • 2020 年 11 月に Helm 2 はサポート終了となりました。 2025 年 3 月 30 日以降、Azure Container Registry は Helm 2 をサポートしなくなります。 そのため、従来の "Helm リポジトリ" 機能も廃止されます。 すぐに Helm 3 に移行することをお勧めします。
  • 2025 年 1 月 21 日以降、CLI コマンドの az acr helm push は廃止され、新しい Helm チャートはレガシ Helm リポジトリにプッシュされなくなります。
  • 2025 年 3 月 30 日以降、CLI コマンド グループ az acr helm は廃止され、Azure Container Registry のすべてのレガシ Helm リポジトリ機能は終了します。
  • OCI 成果物として保存されていないすべての Helm chart は、2025 年 3 月 30 日に Azure Container Registry から削除されます。
  • Helm リポジトリに保存されているすべての Helm chart を検索する方法については、az acr helm list の記事を参照してください。使用している Helm chart が一覧表示されている場合、それはレガシ Helm リポジトリに保存されており、削除されるリスクがあります。

Helm 3 か Helm 2 か

Helm グラフを格納、管理、インストールするには、Helm CLI のコマンドを使用します。 Helm のメジャー リリースには Helm 3 と Helm 2 が含まれています。 バージョン間の違いの詳細については、バージョンに関する FAQ を参照してください。

Azure Container Registry で Helm グラフをホストするには、Helm3 を使用する必要があります。 Helm 3 の場合:

  • Azure Container Registry のリポジトリに、Helm グラフを格納して管理できます
  • Helm グラフをレジストリに OCI 成果物として格納します。 Azure Container Registry では、Helm チャートなどの OCI 成果物に対する GA サポートが提供されます。
  • helm registry login または az acr login コマンドを使用して、レジストリで認証します。
  • helm コマンドを使用して、レジストリ内の Helm グラフをプッシュ、プル、管理します
  • helm install を使用して、レジストリから Kubernetes クラスターにグラフをインストールします。

機能サポート

Azure Container Registry では、Helm 3 (現行) と Helm 2 (非推奨) のどちらを使用しているかに応じて、固有の Helm グラフ管理機能がサポートされます。

機能 Helm 2 Helm 3
az acr helm コマンドを使用してグラフを管理する ✔️
OCI 成果物としてグラフを格納する ✔️
Azure portal で az acr repository コマンドおよびリポジトリ ブレードを使用してグラフを管理する ✔️

グラフのバージョンの互換性

次の Helm グラフのバージョン は Azure Container Registry に格納でき、Helm 2 および Helm 3 クライアントによってインストールされます。

バージョン Helm 2 Helm 3
apiVersion v1 ✔️ ✔️
apiVersion v2 ✔️

Helm 2 から Helm 3 への移行

Helm 2 と Azure Container Registry を使用してグラフを格納してデプロイしたことがある場合、Helm 3 に移行することをお勧めします。 参照トピック

前提条件

この記事のシナリオでは、次のリソースが必要です。

  • Azure サブスクリプションの Azure コンテナー レジストリ。 必要に応じて、Azure portal または Azure CLI を使用してレジストリを作成します。
  • Helm クライアント バージョン 3.7 以降 - 現在のバージョンを確認するには、helm version を実行します。 Helm のインストール方法とアップグレード方法について詳しくは、「Installing Helm (Helm のインストール)」をご覧ください。 以前のバージョンの Helm 3 からアップグレードする場合は、リリース ノートを確認してください。
  • Helm グラフをインストールする Kubernetes クラスター。 必要に応じて、Azure CLI、Azure PowerShell、または Azure portal を使用して AKS クラスターを作成します。
  • Azure CLI バージョン 2.0.71 以降 - バージョンを確認するには az --version を実行します。 インストールまたはアップグレードする必要がある場合は、Azure CLI のインストールに関するページを参照してください。

Helm クライアントを設定する

helm version コマンドを使用して、Helm 3 がインストールされていることを確認します。

helm version

注意

以前のバージョンの OCI サポートは試験的であったため、指定されるバージョンは少なくとも 3.8.0 である必要があります。

ターゲット レジストリで次の環境変数を設定します。 ACR_NAME はレジストリ リソース名です。 ACR レジストリの URL が myregistry.azurecr.io の場合、ACR_NAME を myregistry に設定します。

ACR_NAME=<container-registry-name>

サンプル グラフを作成する

次のコマンドを使用して、テスト グラフを作成します。

mkdir helmtest

cd helmtest
helm create hello-world

基本的な例として、ディレクトリを templates フォルダーに変更し、まずその内容を削除します。

cd hello-world/templates
rm -rf *

次のコマンドを実行して、templates フォルダー内に configmap.yaml というファイルを作成します。

cat <<EOF > configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-world-configmap
data:
  myvalue: "Hello World"
EOF

この例の作成と実行の詳細については、Helm ドキュメントの「Getting Started」を参照してください。

グラフをローカル アーカイブに保存する

ディレクトリを hello-world サブディレクトリに変更します。 次に、helm package を実行して、グラフをローカル アーカイブに保存します。

次の例では、グラフは Chart.yaml 内の名前とバージョンで保存されます。

cd ..
helm package .

出力は次のようになります。

Successfully packaged chart and saved it to: /my/path/hello-world-0.1.0.tgz

レジストリで認証する

helm registry login を実行してレジストリで認証します。 サービス プリンシパルの資格情報、ユーザー ID、リポジトリスコープのトークンなど、シナリオに適したレジストリ資格情報を渡すことができます。

  • レジストリに対するプルアクセス許可とプッシュアクセス許可 (AcrPush ロール) を使用して、Microsoft Entra サービス プリンシパルで認証します。 
    SERVICE_PRINCIPAL_NAME=<acr-helm-sp>
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \
          --scopes $(az acr show --name $ACR_NAME --query id --output tsv) \
           --role acrpush \
          --query "password" --output tsv)
USER_NAME=$(az identity show -n $SERVICE_PRINCIPAL_NAME -g $RESOURCE_GROUP_NAME --subscription $SUBSCRIPTION_ID --query "clientId" -o tsv)
  • AD トークンを使用して Helm チャートをプッシュおよびプルするために、 個々の Microsoft Entra ID で認証します。 
    USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
  • リポジトリスコープのトークンを使用して認証します (プレビュー)。 
    USER_NAME="helmtoken"
PASSWORD=$(az acr token create -n $USER_NAME \
                  -r $ACR_NAME \
                  --scope-map _repositories_admin \
                  --only-show-errors \
                  --query "credentials.passwords[0].value" -o tsv)
  • その後、helm registry login で資格情報を指定します。 
    helm registry login $ACR_NAME.azurecr.io \
  --username $USER_NAME \
  --password $PASSWORD

OCI 成果物としてグラフをレジストリにプッシュする

Helm 3 CLI で helm push コマンドを実行して、完全修飾ターゲット リポジトリにグラフ アーカイブをプッシュします。 グラフ名の単語を区切り、小文字と数字のみを使用します。 次の例では、ターゲット リポジトリの名前空間が helm/hello-world で、グラフに 0.1.0 というタグが付けられています。

helm push hello-world-0.1.0.tgz oci://$ACR_NAME.azurecr.io/helm

プッシュが成功すると、出力は次のようになります。

Pushed: <registry>.azurecr.io/helm/hello-world:0.1.0
digest: sha256:5899db028dcf96aeaabdadfa5899db02589b2899b025899b059db02

リポジトリのグラフ一覧

Azure コンテナー レジストリに格納されているイメージと同様に、az acr repository コマンドを使用して、グラフをホストしているリポジトリと、グラフのタグとマニフェストを表示できます。

たとえば、az acr repository show を実行して、前の手順で作成したリポジトリのプロパティを表示します。

az acr repository show \
  --name $ACR_NAME \
  --repository helm/hello-world

出力は次のようになります。

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2021-10-05T12:11:37.6701689Z",
  "imageName": "helm/hello-world",
  "lastUpdateTime": "2021-10-05T12:11:37.7637082Z",
  "manifestCount": 1,
  "registry": "mycontainerregistry.azurecr.io",
  "tagCount": 1
}

az acr manifest list-metadata コマンドを実行して、リポジトリに保存されているグラフの詳細を表示します。 次に例を示します。

az acr manifest list-metadata \
  --registry $ACR_NAME \
  --name helm/hello-world

出力 (この例では省略されています) には、application/vnd.cncf.helm.config.v1+json の configMediaType が表示されます。

[
  {
    [...]
    "configMediaType": "application/vnd.cncf.helm.config.v1+json",
    "createdTime": "2021-10-05T12:11:37.7167893Z",
    "digest": "sha256:0c03b71c225c3ddff53660258ea16ca7412b53b1f6811bf769d8c85a1f0663ee",
    "imageSize": 3301,
    "lastUpdateTime": "2021-10-05T12:11:37.7167893Z",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "tags": [
      "0.1.0"
    ]

Helm グラフをインストールする

レジストリにプッシュした Helm グラフをインストールするには、helm install を実行します。 グラフのタグは、--version パラメーターを使用して渡します。 myhelmtest などのリリース名を指定するか、--generate-name パラメーターを渡します。 次に例を示します。

helm install myhelmtest oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

グラフのインストールが成功した後の出力は次のようになります。

NAME: myhelmtest
LAST DEPLOYED: Tue Oct  4 16:59:51 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

インストールされていることを確認するには、helm get manifest コマンドを実行します。

helm get manifest myhelmtest

このコマンドは、configmap.yaml テンプレート ファイル内の YAML データを返します。

クラスター上のグラフのリリースをアンインストールするには、helm uninstall を実行します。

helm uninstall myhelmtest

グラフをローカル アーカイブにプルする

必要に応じて、helm pull を使用して、コンテナー レジストリからローカル アーカイブにグラフをプルできます。 グラフのタグは、--version パラメーターを使用して渡します。 ローカル アーカイブが現在のパスに存在する場合は、このコマンドによって上書きされます。

helm pull oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

レジストリからグラフを削除する

コンテナー レジストリからグラフを削除するには、az acr repository delete コマンドを使用します。 次のコマンドを実行し、プロンプトが表示されたら操作を確認します。

az acr repository delete --name $ACR_NAME --image helm/hello-world:0.1.0

レジストリを移行して Helm OCI 成果物を格納する

以前に Helm 2 と az acr helm コマンドを使用して Azure Container Registry をグラフ リポジトリとして設定した場合、Helm 3 クライアントにアップグレードすることをお勧めします。 次に、次の手順に従って、グラフを OCI 成果物としてレジストリに格納します。

重要

  • Helm 2 スタイル (index.yaml ベース) のグラフ リポジトリから OCI 成果物リポジトリへの移行が完了したら、Helm CLI と az acr repository コマンドを使用してグラフを管理します。 この記事の前のセクションをご覧ください。
  • Helm OCI 成果物リポジトリは、helm search や helm repo list などの Helm コマンドを使用して検出できません。 グラフを OCI 成果物として格納するために使用される Helm コマンドの詳細については、Helm のドキュメントを参照してください。

OCI サポートを有効にする (Helm v3.8.0 では既定で有効)

Helm 3 クライアントを使用していることを確認します。

helm version

Helm v3.8.0 以降を使用している場合、これは既定で有効になっています。 下位バージョンを使用している場合は、環境変数を設定して OCI サポートを有効にすることができます。

export HELM_EXPERIMENTAL_OCI=1

現在のグラフを一覧表示する

レジストリに現在格納されているグラフを一覧表示します。ここでは myregistry という名前です。

helm search repo myregistry

出力には、グラフとグラフのバージョンが表示されます。

NAME                            CHART VERSION   APP VERSION     DESCRIPTION                                       
myregistry/ingress-nginx        3.20.1          0.43.0          Ingress controller for Kubernetes...
myregistry/wordpress            9.0.3           5.3.2           Web publishing platform for building...
[...]

グラフ アーカイブをローカルにプルする

リポジトリ内のグラフごとに、グラフ アーカイブをローカルにプルし、ファイル名をメモします。

helm pull myregisry/ingress-nginx
ls *.tgz

ingress-nginx-3.20.1.tgz などのローカル グラフ アーカイブが作成されます。

OCI 成果物としてグラフをレジストリにプッシュする

レジストリにログインします。

az acr login --name $ACR_NAME

各グラフ アーカイブをレジストリにプッシュします。 例:

helm push ingress-nginx-3.20.1.tgz oci://$ACR_NAME.azurecr.io/helm

グラフをプッシュした後、それがレジストリに格納されているのを確認します。

az acr repository list --name $ACR_NAME

すべてのグラフをプッシュした後、必要に応じて、Helm 2 スタイルのグラフ リポジトリをレジストリから削除します。 これにより、レジストリ内のストレージが減少します。

helm repo remove $ACR_NAME

次のステップ

  • Helm グラフを作成してデプロイする方法の詳細については、Helm グラフの開発に関するページを参照してください。
  • Azure Kubernetes Service (AKS) での Helm を使用したアプリケーションのインストールについて詳細を確認します。
  • Helm グラフは、コンテナーのビルド プロセスの一部として使用できます。 詳細については、Azure Container Registry タスクの使用に関するページを参照してください。