將 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 loginaz 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 3 起,az acr helm 命令與 Helm 2 用戶端的搭配使用已被取代。 在命令移除之前,至少會提供 3 個月的通知。

圖表的版本相容性

下列 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。 請參閱:

必要條件

本文情節需要下列資源:

  • Azure 訂用帳戶中的 Azure 容器登錄。 如果需要,使用 Azure 入口網站Azure CLI 來建立登錄。
  • Helm 用戶端 3.7 版或更新版本 - 執行 helm version 以尋找目前的版本。 如需有關如何安裝及升級 Helm 的詳細資訊,請參閱安裝 Helm。 如果您從舊版 Helm 3 升級,請檢閱版本資訊
  • 您將在其中安裝 Helm 圖表的 Kubernetes 叢集。 如有需要,請建立 AKS 叢集 [使用 Azure CLI][./learn/quick-kubernetes-deploy-cli]、[使用 Azure PowerShell][./learn/quick-kubernetes-deploy-powershell],或 [使用 Azure 入口網站][./learn/quick-kubernetes-deploy-portal]。
  • 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 以向登錄進行驗證。 您可以傳遞適合您情節的登錄認證,例如服務主體認證、使用者身分識別或存放庫範圍的權杖。

  • 使用向登錄提取和推送權限 (AcrPush 角色) 向 Azure Active Directory 服務主體進行驗證。
    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 ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)
    
  • 使用個別 Azure AD 身分識別進行驗證,以使用 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+jsonconfigMediaType

[
  {
    [...]
    "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 searchhelm 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

下一步