通过免密组件拉取容器镜像 - 容器服务 Kubernetes 版 ACK

通过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用户容器镜像服务中的私有镜像。支持通过跨账号授权或AccessKey ID和AccessKey Secret配置的方式，拉取其他RAM用户的私有镜像。支持拉取容器镜像服务企业版实例和个人版实例（兼容场景）中的私有镜像。
集群及版本	集群版本不低于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组件依赖权限的公告。

登录容器服务管理控制台，在左侧导航栏选择集群。
在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择运维管理 > 组件管理。
在组件管理页面，单击安全页签，找到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配置项。

通过控制台配置

登录容器服务管理控制台，在左侧导航栏选择集群。
在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择配置管理 > 配置项。
在配置项页面顶部的命名空间下拉列表，选择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配置项。

通过控制台配置

登录容器服务管理控制台，在左侧导航栏选择集群。
在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择配置管理 > 配置项。
在配置项页面顶部的命名空间下拉列表，选择kube-system，然后找到配置项acr-configuration，设置配置项的值。
如果您没有acr-configuration配置项，请参见创建配置项。关于如何更新配置项，请参见修改配置项。
- 单击其右侧的编辑，设置配置项键和值。
- 单击其右侧的YAML编辑，设置配置项键和值。

通过kubectl命令行配置

执行以下命令，打开acr-configuration配置项的编辑页。
```
kubectl edit cm acr-configuration -n kube-system
```
根据实际情况设置acr-configuration配置项的值。