通過aliyun-acr-credential-helper組件可以在自建Kubernetes叢集中免密拉取ACR個人版或企業版私人鏡像。本文列舉兩個情境介紹如何使用免密組件拉取私人鏡像。
前提條件
已建立註冊叢集，並將自建Kubernetes叢集接入註冊叢集。具體操作，請參見通過控制台建立註冊叢集、通過onectl建立註冊叢集。
已通過kubectl串連註冊叢集。具體操作，請參見擷取叢集KubeConfig並通過kubectl工具串連叢集。
使用說明
免密組件通過讀取叢集內kube-system命名空間中acr-configuration的配置，進行私人鏡像拉取。免密組件配置完成後將會在叢集中自動建立Secret，並關聯到配置中已指定的ServiceAccount。任何使用此ServiceAccount的Pod都會預設使用免密組件產生的Secret進行鏡像拉取，從而達到免密拉取鏡像的效果。
針對新建立ServiceAccount部署應用的情境（例如部署Helm Chart），免密組件ServiceAccount關聯Secret可能存在延遲，建議使用Webhook功能。
免密組件拉取私人鏡像的使用條件如下。
類別 | 說明 |
鏡像 |
|
叢集及版本 |
|
注意事項
類別 | 注意事項 |
拉取憑證imagePullSecrets |
|
ServiceAccount |
|
地區 | 確認Kubernetes叢集所屬地區與要拉取的鏡像所在地區是否一致。 預設配置僅可以拉取本地區的鏡像。如需跨地區拉取鏡像，請參見下文情境二：配置跨地區拉取鏡像。 |
YAML格式 | 修改kube-system命名空間中的acr-configuration配置項時，請確認縮排與給出的情境樣本是否相同。建議直接複製對應情境的YAML內容到編輯器，修改對應的值，然後直接應用到叢集，以保證YAML格式的正確性。 |
在註冊叢集中配置免密組件
步驟一：為免密組件配置RAM許可權
通過onectl配置
在本地安裝配置onectl。具體操作，請參見通過onectl管理註冊叢集。
執行以下命令，為免密組件配置RAM許可權。
onectl ram-user grant --addon aliyun-acr-credential-helper預期輸出：
Ram policy ack-one-registered-cluster-policy-aliyun-acr-credential-helper granted to ram user ack-one-user-ce313528c3 successfully.
通過控制台配置
在註冊叢集中安裝組件前，您需要在接入叢集中設定AccessKey用來訪問雲端服務的許可權。設定AccessKey前，您需要建立RAM使用者並為其添加訪問相關雲資源的許可權。
建立RAM使用者。具體操作，請參見建立RAM使用者。
建立權限原則。具體操作，請參見建立自訂權限原則。
權限原則模板如下所示：
{ "Version": "1", "Statement": [ { "Action": [ "cr:GetAuthorizationToken", "cr:ListInstanceEndpoint", "cr:PullRepository" ], "Resource": [ "*" ], "Effect": "Allow" } ] }為RAM使用者添加許可權。具體操作，請參見為RAM使用者授權。
為RAM使用者建立AccessKey。具體操作，請參見擷取AccessKey。
使用AccessKey在註冊叢集中建立名為alibaba-addon-secret的Secret資源。
安裝免密組件時將自動引用此AccessKey訪問對應的雲端服務資源。
kubectl -n kube-system create secret generic alibaba-addon-secret --from-literal='access-key-id=<your access key id>' --from-literal='access-key-secret=<your access key secret>'說明<your access key id>及<your access key secret>為上一步擷取的AccessKey資訊。
步驟二：升級並配置免密組件
在使用免密組件拉取鏡像前，您需要安裝並配置免密組件。
通過onectl安裝
執行以下命令，安裝免密組件。
onectl addon install aliyun-acr-credential-helper預期輸出：
Addon aliyun-acr-credential-helper, version **** installed.如果您已安裝免密組件，請確保組件為最新版本。否則，請執行以下命令，升級免密組件。
onectl addon upgrade aliyun-acr-credential-helper預期輸出：
Addon aliyun-acr-credential-helper upgraded to version ****.通過控制台安裝
如果您已安裝免密組件，請確保該組件為最新版本。否則，請升級該組件。此組件升級不會對業務造成影響。具體操作，請參見管理組件。關於aliyun-acr-credential-helper組件更多資訊，請參見aliyun-acr-credential-helper。
免密組件aliyun-acr-credential-helper升級至最新版本後，會切換該組件所依賴的RAM角色。為相容新老使用者的使用習慣，該組件提供了配置項，您可以自訂依賴於哪個RAM角色。關於切換RAM角色對使用方式的影響，請參見【產品變更】關於變更aliyun-acr-credential-helper組件依賴許可權的公告。
免密組件aliyun-acr-credential-helper升級至最新版本後，會切換該組件所依賴的RAM角色。為相容新老使用者的使用習慣，該組件提供了配置項，您可以自訂依賴於哪個RAM角色。關於切換RAM角色對使用方式的影響，請參見【產品變更】關於變更aliyun-acr-credential-helper組件依賴許可權的公告。
登入Container Service管理主控台，在左側導覽列選擇叢集。
在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，選擇。
在組件管理頁面，單擊安全頁簽，找到aliyun-acr-credential-helper，單擊安裝。
在參數配置頁面，組件使用的許可權模式保持預設值auto，然後單擊確定。
當ACK託管版叢集升級到最新版本，aliyun-acr-credential-helper組件提供了tokenMode配置項，組件安裝後也可以進行修改。組件修改後，Pod將會重建。2023年04月03日之前建立的叢集為老叢集，2023年04月03日及之後建立的叢集為新叢集。具體配置項內容如下。
tokenMode
說明
auto
預設值，表示自動確定是否使用managedRole。新叢集使用managedRole模式，老叢集使用workerRole模式。
managedRole
使用managedRole模式。
workerRole
使用workerRole模式。
免密組件安裝完成後，在拉取鏡像時，需要對免密組件配置項acr-configuration進行配置。
通過控制台配置
登入Container Service管理主控台，在左側導覽列選擇叢集。
在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，選擇組態管理 > 配置項。
在配置項頁面頂部的命名空間下拉式清單，選擇kube-system，然後找到配置項acr-configuration，設定配置項的值。
如果您沒有acr-configuration配置項，請參見建立配置項。關於如何更新配置項，請參見修改配置項。
單擊其右側的編輯，設定配置項鍵和值。
單擊其右側的YAML編輯，設定配置項鍵和值。
通過kubectl命令列配置
執行以下命令，開啟acr-configuration配置項的編輯頁。
kubectl edit cm acr-configuration -n kube-system根據實際情況設定acr-configuration配置項的值。
acr-configuration配置項的鍵和值說明如下。
配置項鍵
配置項鍵說明
配置項值
service-account
將免密認證機制應用於指定的服務賬戶。
說明服務賬戶（ServiceAccount）是指定給運行在Kubernetes叢集內的服務和應用的身份標識。
預設為default。
說明如果要配置多個請以英文半形逗號（,）分隔， 如果設定為
“*”， 表示支援指定命名空間下的所有ServiceAccount。acr-registry-info
容器鏡像的執行個體資訊數組，YAML多行字串格式，每個執行個體以三元組方式配置。
說明執行個體資訊三元組：
instanceId：執行個體ID，企業版執行個體必須配置此項。若要確保個人版正常使用，須在控制台將YAML配置中的
#-instanceId前的#刪除以啟用該項。regionId：可選，預設為本地地區。
domains：可選，預設為相應執行個體的所有網域名稱。若要指定個別網域名稱，多個以英文半形逗號（,）分隔。
預設值為空白，表示免密拉取同地區的個人版執行個體鏡像（相容情境）。
針對企業版容器鏡像執行個體，配置樣本如下：
- instanceId: <cri-instanceId> regionId: "cn-hangzhou" domains: "xxx.com,yyy.com"watch-namespace
期望能免密拉取鏡像的Namespace。
預設值為default。當取值為all時，表示期望所有Namespace均能免密拉取。如需配置多個Namespace時，以英文半形逗號（,）分隔。
說明推薦配置生效Namespace為您的業務Namespace，盡量避免配置all或者叢集系統組件相關Namespace，以免影響叢集系統組件鏡像的拉取。
expiring-threshold
本機快取憑證到期閾值。
預設值為15m。
說明建議使用15min。即在緩衝到期15分鐘前進行憑證更新。
情境一：拉取個人版執行個體和企業執行個體的私人鏡像
註冊叢集支援同時拉取企業版和個人版的私人鏡像，只拉取企業版的私人鏡像，只拉取個人版的私人鏡像。根據您的使用情境，按照以下方式修改配置項acr-configuration中的configMap。具體操作，請參見配置組件。配置內容如下。
企業版
apiVersion:v1 kind:ConfigMap metadata: name:acr-configuration namespace:kube-system selfLink:/api/v1/namespaces/kube-system/configmaps/acr-configuration data: acr-api-version:"2018-12-01" acr-registry-info:|- -instanceId:"cri-xxx" # 控制台預設參數為#-instanceId，需要將#號去掉並必須配置此項。 regionId:"cn-hangzhou" expiring-threshold:15m service-account:default watch-namespace:all個人版
apiVersion:v1 kind:ConfigMap metadata: name:acr-configuration namespace:kube-system selfLink:/api/v1/namespaces/kube-system/configmaps/acr-configuration data: acr-api-version:"2018-12-01" acr-registry-info:|- -instanceId:"" # 控制台預設參數為#-instanceId，需要將#去掉保持預設。 regionId:"cn-hangzhou" expiring-threshold:15m service-account:default watch-namespace:all
您可以通過以下兩種方式設定acr-configuration配置項。
通過控制台配置
登入Container Service管理主控台，在左側導覽列選擇叢集。
在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，選擇組態管理 > 配置項。
在配置項頁面頂部的命名空間下拉式清單，選擇kube-system，然後找到配置項acr-configuration，設定配置項的值。
如果您沒有acr-configuration配置項，請參見建立配置項。關於如何更新配置項，請參見修改配置項。
單擊其右側的編輯，設定配置項鍵和值。
單擊其右側的YAML編輯，設定配置項鍵和值。
通過kubectl命令列配置
執行以下命令，開啟acr-configuration配置項的編輯頁。
kubectl edit cm acr-configuration -n kube-system根據實際情況設定acr-configuration配置項的值。
情境二：配置跨地區拉取鏡像許可權
如果需要拉取的鏡像與當前註冊叢集不屬於同一地區的時候，需要修改配置項acr-configuration中的configMap。
例如，個人版的鏡像倉庫同時拉取北京地區與杭州地區的鏡像，配置如下。具體操作，請參見配置組件。
data:
service-account: "default"
watch-namespace: "all"
expiring-threshold: "15m"
notify-email: "**@aliyuncs.com"
acr-registry-info: |
- instanceId: ""
regionId: cn-beijing
- instanceId: ""
regionId: cn-hangzhou 您可以通過以下兩種方式設定acr-configuration配置項。
通過控制台配置
登入Container Service管理主控台，在左側導覽列選擇叢集。
在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，選擇組態管理 > 配置項。
在配置項頁面頂部的命名空間下拉式清單，選擇kube-system，然後找到配置項acr-configuration，設定配置項的值。
如果您沒有acr-configuration配置項，請參見建立配置項。關於如何更新配置項，請參見修改配置項。
單擊其右側的編輯，設定配置項鍵和值。
單擊其右側的YAML編輯，設定配置項鍵和值。
通過kubectl命令列配置
執行以下命令，開啟acr-configuration配置項的編輯頁。
kubectl edit cm acr-configuration -n kube-system根據實際情況設定acr-configuration配置項的值。