將 Helm 圖表推送並提取至 Azure 容器登錄

發行項
09/29/2024

若要快速管理及部署 Kubernetes 的應用程式，您可以使用開放原始碼 Helm 套件管理員。使用 Helm 時，應用程式套件會定義成在 Helm 圖表存放庫中收集和儲存的「圖表」。

本文說明如何使用 Helm 3 命令，並將圖表儲存為 OCI 成品，在 Azure 容器登錄中裝載 Helm 圖表存放庫。在大多數情節下，您會為您開發的應用程式建置並上傳自己的圖表。如需如何建置您自己 Helm 圖表的詳細資訊，請參閱圖表範本開發人員指南。您也可以從另一個 Helm 存放庫儲存現有的 Helm 圖表。

注意

已使用 Helm 3 命令更新本文。 Helm 3.7 包含 Helm CLI 命令的變更，以及舊版 Helm 3 中引進的 OCI 支援。根據設計，helm 會隨著版本更新而進階。我們建議您使用 3.7.2 或更新版本。

重要

Helm 2 的生命週期已在 2020 年 11 月結束。從 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 圖表將於 2025 年 3 月 30 日從 Azure Container Registry 中刪除。
了解如何在這裡尋找儲存在 Helm 存放庫中的所有 Helm 圖表: az acr helm list。如果您使用的 Helm 圖表有列出，則代表它儲存在舊版 Helm 存放庫中，且有刪除風險。

Helm 3 或 Helm 2？

若要儲存、管理及安裝 Helm 圖表，請使用 Helm CLI 中的命令。主要 Helm 版本包括 Helm 3 和 Helm 2。如需版本差異的詳細資訊，請參閱版本常見問題。

Helm 3 應該用來裝載 Azure Container Registry 中的 Helm 圖表。您可以使用 Helm 3：

可以在 Azure 容器登錄的存放庫中儲存和管理 Helm 圖表
將 Helm 圖表儲存在登錄中做為 OCI 成品。 Azure Container Registry 提供 OCI 成品的 GA 支援，包括 Helm 圖表。
使用 helm registry login 或 az acr login 命令向登錄進行驗證。
使用 helm 命令在登錄中推送、提取和管理 Helm 圖表
使用 helm install 將圖表從登錄安裝至 Kubernetes 叢集。

功能支援

取決於您使用的是 Helm 3 (最新) 還是 Helm 2 (已被取代)，Azure Container Registry 支援特定的 Helm 圖表管理功能。

功能	Helm 2	Helm 3
使用 `az acr helm` 命令管理圖表	✔️
將圖表儲存為 OCI 成品		✔️
使用 `az acr repository` 命令和 Azure 入口網站中的 [存放庫] 刀鋒視窗來管理圖表		✔️

圖表的版本相容性

下列 Helm 圖表版本可以儲存在 Azure Container Registry 中，而且可由 Helm 2 和 Helm 3 用戶端安裝。

版本	Helm 2	Helm 3
apiVersion 第 1 版	✔️	✔️
apiVersion 第 2 版		✔️

從 Helm 2 移轉至 Helm 3

如果您先前已使用 Helm 2 和 Azure Container Registry 來儲存和部署圖表，建議您移轉至 Helm 3。請參閱：

在 Helm 文件中將 Helm 2 移轉至 3。
移轉登錄以儲存 Helm OCI 成品 (在本文稍後)

必要條件

本文情節需要下列資源：

Azure 訂用帳戶中的 Azure 容器登錄。如果需要，使用 Azure 入口網站或 Azure CLI 來建立登錄。
Helm 用戶端 3.7 版或更新版本 - 執行 helm version 以尋找目前的版本。如需有關如何安裝及升級 Helm 的詳細資訊，請參閱安裝 Helm。如果您從舊版 Helm 3 升級，請檢閱版本資訊。
您將在其中安裝 Helm 圖表的 Kubernetes 叢集。如有需要，請使用 Azure CLI、使用 Azure PowerShell 或使用 Azure 入口網站建立 AKS 叢集。
Azure CLI 2.0.71 版或更新版本 - 請執行 az --version 來找出版本。如果您需要安裝或升級，請參閱安裝 Azure CLI。

設定 Helm 用戶端

使用 helm version 命令來確認您已安裝 Helm 3：

helm version

注意

指出的版本至少必須是 3.8.0，因為舊版中的 OCI 支援是實驗性的。

設定目標登錄的下列環境變數。 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 文件中的使用者入門。

將圖表儲存至本地封存

將目錄變更為 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 以向登錄進行驗證。您可以傳遞適合您情節的登錄認證，例如服務主體認證、使用者身分識別或存放庫範圍的權杖。

使用具有 Microsoft Entra 提取和推送權限的服務主體 (AcrPush 角色) 向登錄進行驗證。

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)

使用個別 Microsoft Entra 身分識別進行驗證，以使用 AD 權杖推送和提取 Helm 圖表。

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 Chart

執行 helm install 以安裝您推送至登錄的 Helm 圖表。圖表標籤會使用 --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 容器登錄設定為圖表存放庫，建議您升級至 Helm 3 用戶端。然後，請遵循下列步驟，將圖表儲存為登錄中的 OCI 成品。

重要

完成從 Helm 2 樣式 (index.yaml 型) 圖表存放庫至 OCI 成品存放庫的移轉之後，請使用 Helm CLI 和 az acr repository 命令來管理圖表。請參閱本文的上一節。
無法使用 helm search 和 helm repo list 之類的 Helm 命令來探索 Helm OCI 成品存放庫。如需用來將圖表儲存為 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 工作。

共用方式為