通過免密組件拉取容器鏡像 - Container Service for Kubernetes

通過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功能。

免密組件拉取私人鏡像的使用條件如下。

類別	說明
鏡像	支援拉取叢集當前RAM使用者Container Registry中的私人鏡像。支援通過跨帳號授權或AccessKey ID和AccessKey Secret配置的方式，拉取其他RAM使用者的私人鏡像。支援拉取Container Registry企業版執行個體和個人版執行個體（相容情境）中的私人鏡像。
叢集及版本	叢集版本不低於1.11.2。否則，請您手動升級。具體操作，請參見升級ACK叢集。支援叢集多命名空間免密拉取。

注意事項

類別	注意事項
拉取憑證imagePullSecrets	在Kubernetes資源（例如無狀態應用Deployment）模板中配置拉取憑證（imagePullSecret）會導致免密組件失效。如需使用免密組件，請勿手動設定拉取憑證（imagePullSecret）。免密組件預設覆蓋ACK中所有命名空間中預設的ServiceAccount的imagePullSecrets欄位。被覆蓋的ServiceAccount會隨著對應kube-system命名空間中acr-configuration配置項的service-account欄位變動而變動。
ServiceAccount	如果部署的Kubernetes資源（例如無狀態應用Deployment）使用了自訂的ServiceAccount，需先調整免密組件設定檔中Service-Account欄位，使其作用於自訂的ServiceAccount，再進行部署資源操作。在叢集中建立新的ServiceAccount一段時間後，當擷取imagepullsecrets欄位的傳回值包含以acr-credential開頭的Secret時，免密組件產生的憑證才會更新到應用使用的ServiceAccount中，使用ServiceAccount的應用才能使用憑證拉取鏡像。如果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組件依賴許可權的公告。

登入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中的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配置項的值。