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

[アーティクル]
10/31/2023

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

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

重要

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

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 3 以降、Helm 2 クライアントで使用する az acr helm コマンドは非推奨となります。コマンドが削除される少なくとも 3 か月前に通知が提供されます。

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

次の 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 に移行することをお勧めします。参照トピック

Helm ドキュメントの Helm 2 から 3 への移行
この記事の後半にあるレジストリを移行して Helm OCI 成果物を格納する

前提条件

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

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 タスクの使用に関するページを参照してください。

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

Helm 3 か Helm 2 か

機能サポート

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

Helm 2 から Helm 3 への移行

前提条件

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

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

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

レジストリで認証する

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

リポジトリのグラフ一覧

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

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

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

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

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

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

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

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

次のステップ

その他のリソース

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

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

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

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

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