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

  • 發行項

若要快速管理及部署 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 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 叢集。

功能支援

Azure Container Registry 支援特定的 Helm 圖表管理功能，取決於您使用的是 Helm 3 （目前） 或 Helm 2 （已淘汰）。

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

注意

從 Helm 3 起， az acr helm 命令將取代與 Helm 2 用戶端搭配使用。 在命令移除之前，至少會提供 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 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 Docs 中的使用者入門 。

將圖表儲存至本機封存

將目錄變更為 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 push在 Helm 3 CLI 中執行 命令，將圖表封存推送至完整目標存放庫。 分隔圖表名稱中的單字，並且只使用小寫字母和數位。 在下列範例中，目標存放庫命名空間為 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

在此範例中縮寫的輸出會顯示 configMediaType 的 application/vnd.cncf.helm.config.v1+json ：

[
  {
    [...]
    "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 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 OCI 成品存放庫無法使用 Helm 命令來探索，例如 helm search 和 helm repo list 。 如需用來將圖表儲存為 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

下一步