通過aliyun-acr-credential-helper組件可以在自建Kubernetes集群中免密拉取ACR個人版或企業版私有鏡像。本文列舉兩個場景介紹如何使用免密組件拉取私有鏡像。
前提條件
已創建注冊集群，并將自建Kubernetes集群接入注冊集群。具體操作，請參見創建注冊集群。
已通過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組件依賴權限的公告。
登錄容器服務管理控制臺，在左側導航欄選擇集群。
在集群列表頁面，單擊目標集群名稱，然后在左側導航欄，選擇。
在組件管理頁面，單擊安全頁簽，找到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中的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配置項。
通過控制臺配置
通過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配置項。
通過控制臺配置
通過kubectl命令行配置
執行以下命令，打開acr-configuration配置項的編輯頁。
kubectl edit cm acr-configuration -n kube-system根據實際情況設置acr-configuration配置項的值。