通过aliyun-acr-credential-helper在自建Kubernetes集群免密拉取ACR私有镜像

通过aliyun-acr-credential-helper组件可以在自建Kubernetes集群中免密拉取ACR个人版或企业版私有镜像。本文列举两个场景介绍如何使用免密组件拉取私有镜像。

前提条件

您需要创建一个注册集群，并将自建Kubernetes集群接入注册集群。具体操作，请参见创建注册集群并接入本地数据中心集群。
通过kubectl连接注册集群。具体操作，请参见获取集群KubeConfig并通过kubectl工具连接集群。

使用限制

使用免密组件涉及的镜像及集群限制如下：

镜像
- 支持拉取容器镜像服务企业版实例和个人版实例中的私有镜像。
- 支持拉取集群当前用户容器镜像服务中的私有镜像，通过跨账号授权或AccessKey ID和AccessKey Secret配置可以拉取其他用户的私有镜像。
- 支持拉取容器镜像服务企业版实例和个人版实例（兼容场景）中的私有镜像。
集群
- 支持集群多命名空间免密拉取。
- 集群版本不低于1.11.2。否则，请您手动升级。具体操作，请参见升级ACK集群K8s版本。

注意事项

在Kubernetes资源（例如无状态应用Deployment）模板中配置拉取凭证（imagePullSecret）会导致免密组件失效，如果需使用免密组件，请避免手工配置拉取凭证（imagePullSecret）。
如果部署的Kubernetes资源（例如无状态应用Deployment）使用了自定义的ServiceAccount，需先调整免密组件配置文件中Service-Account字段，使其作用于自定义的ServiceAccount，再进行部署资源操作。
在集群中创建新的ServiceAccount一段时间后，免密插件生成的凭证才会更新到应用使用到的ServiceAccount中，使用ServiceAccount的应用才能使用凭证拉取镜像。如果创建完ServiceAccount之后立即创建应用可能会出现因鉴权失败无法拉取的情况。
免密插件默认覆盖ACK中所有命名空间中默认的ServiceAccount中的imagePullSecrets字段。被覆盖的ServiceAccount会随着对应kube-system命名空间中acr-configuration配置项中的service-account字段变动而变动。
在修改kube-system命名空间中的acr-configuration配置项时，请确认缩进是否与给出的场景的例子相同。建议直接复制对应场景的YAML内容到编辑器中，修改对应的值然后直接应用到集群，以保证YAML格式的正确性。

在注册集群中配置免密组件

步骤一：为免密组件配置RAM权限

在注册集群中安装组件前，您需要在接入集群中设置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信息。

步骤二：升级并配置免密组件

在使用免密组件拉取镜像前，您可能需要升级并配置组件。

升级aliyun-acr-credential-helper组件。
关于aliyun-acr-credential-helper组件更多信息，请参见aliyun-acr-credential-helper。此组件升级不会对业务造成影响。
1. 登录容器服务管理控制台，在左侧导航栏选择集群。
2. 在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择运维管理 > 组件管理。
3. 在组件管理页面，单击安全页签，找到aliyun-acr-credential-helper，单击升级。

设置acr-configuration配置项。

方式一：通过控制台方式设置acr-configuration配置项。

登录容器服务管理控制台，在左侧导航栏选择集群。
在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择配置管理 > 配置项。

在配置项页面的上方命名空间下拉框中，选择kube-system，然后找到配置项acr-configuration，然后通过以下两种方式配置acr-configuration。

方式一：单击其右侧的编辑，设置配置项键和值。
如果您没有acr-configuration配置项，请参见创建配置项。关于如何更新配置项，请参见修改配置项。
方式二：单击其右侧的YAML编辑，设置配置项键和值。

acr-configuration配置项的键和值说明如下。


配置项键	配置项键说明	配置项值
service-account	使免密组件作用于指定的服务账号。	默认为default。说明如果要配置多个请以英文半角逗号（,）分隔，如果设置为“*”，表示支持所有命名空间下的所有ServiceAccount。
acr-registry-info	容器镜像的实例信息数组，YAML多行字符串格式，每个实例以三元组方式配置。说明实例信息三元组： instanceId：实例ID，企业版实例必须配置此项。 regionId：可选，默认为本地地域。 domains：可选，默认为相应实例的所有域名。若要指定个别域名，多个以英文半角逗号（,）分隔。	默认值为空，表示免密拉取同地域的个人版实例镜像（兼容场景）。针对企业版容器镜像实例，配置示例如下： `- instanceId: "cri-instanceId" regionId: "cn-hangzhou" domains: "xxx.com,yyy.com"`
watch-namespace	期望能免密拉取镜像的Namespace。	默认值为default。说明当取值为all时，表示期望所有Namespace都能免密拉取。如果需要配置多个Namespace时，以英文半角逗号（,）分隔。
expiring-threshold	本地缓存凭证过期阈值。	默认值为15m。说明建议使用15min。即在缓存过期15分钟前进行凭证更新。

方式二：通过kubectl命令行的方式设置acr-configuration配置项。

执行以下命令打开acr-configuration配置项的编辑页。
```
kubectl edit cm acr-configuration -n kube-system
```

根据实际情况设置acr-configuration配置项的值。

企业版和个人版容器镜像实例下设置acr-configuration配置项的示例如下：

企业版

apiVersion: v1
data:
  acr-api-version: "2018-12-01"
  acr-registry-info: |-
    - instanceId: "cri-xxx"
      regionId: "cn-hangzhou"
  expiring-threshold: 15m
  service-account: default
  watch-namespace: all
kind: ConfigMap
metadata:
 name: acr-configuration
  namespace: kube-system
 selfLink: /api/v1/namespaces/kube-system/configmaps/acr-configuration

个人版

apiVersion: v1
data:
  acr-api-version: "2018-12-01"
  acr-registry-info: |-
    - instanceId: ""
      regionId: "cn-hangzhou"
  expiring-threshold: 15m
  service-account: default
  watch-namespace: all
kind: ConfigMap
metadata:
 name: acr-configuration
 namespace: kube-system
 selfLink: /api/v1/namespaces/kube-system/configmaps/acr-configuration

场景一：拉取个人版实例和企业实例的私有镜像

注册集群支持同时拉取企业版和个人版的私有镜像，只拉取企业版的私有镜像，只拉取个人版的私有镜像。根据您的使用场景，按照以下方式修改配置项acr-configuration中的configMap。具体操作，请参见配置组件。配置内容如下：

企业版

apiVersion: v1
data:
  acr-api-version: "2018-12-01"
  acr-registry-info: |-
    - instanceId: "cri-xxx"
      regionId: "cn-hangzhou"
  expiring-threshold: 15m
  service-account: default
  watch-namespace: all
kind: ConfigMap
metadata:
 name: acr-configuration
  namespace: kube-system
 selfLink: /api/v1/namespaces/kube-system/configmaps/acr-configuration

个人版

apiVersion: v1
data:
  acr-api-version: "2018-12-01"
  acr-registry-info: |-
    - instanceId: ""
      regionId: "cn-hangzhou"
  expiring-threshold: 15m
  service-account: default
  watch-namespace: all
kind: ConfigMap
metadata:
 name: acr-configuration
 namespace: kube-system
 selfLink: /api/v1/namespaces/kube-system/configmaps/acr-configuration

场景二：配置跨地域拉取镜像权限

如果需要拉取的镜像与当前注册集群不属于同一地域的时候，需要修改配置项acr-configuration中的configMap。

例如，个人版的镜像仓库同时拉取北京地域与杭州地域的镜像，配置如下。具体操作，请参见配置组件。

data:
    service-account: "default"
    watch-namespace: "all"
    expiring-threshold: "15m"
    notify-email: "cs@aliyuncs.com"
    acr-registry-info: |
      - instanceId: ""
        regionId: cn-beijing
      - instanceId: ""
        regionId: cn-hangzhou