aliyun-acr-credential-helper是一个可以在ACK集群中免密拉取ACR个人版或企业版私有镜像的组件。该组件会默认安装在所有ACK集群中。本文列举四个场景介绍如何使用免密组件拉取私有镜像。
前提条件
- 您需要创建一个注册集群，并将自建Kubernetes集群接入注册集群。具体操作，请参见创建阿里云注册集群并接入自建Kubernetes集群。
注意
- 在Kubernetes资源（例如无状态应用Deployment）模板中配置拉取凭证（imagePullSecret）会导致免密组件失效，如果需使用免密组件，请避免手工配置拉取凭证（imagePullSecret）。
- 如果部署的Kubernetes资源（例如无状态应用Deployment）使用了自定义的ServiceAccount，需先调整免密组件配置文件中Service-Account字段，使其作用于自定义的ServiceAccount，再进行部署资源操作。
- 在集群中创建新的Service Account一段时间后，免密插件根据ACK集群默认权限生成的ACR私有镜像拉取Token才会更新到应用使用到的Service Account中， 使用Service Account的应用才会使用Token去拉取镜像。如果创建完Service Account之后立即创建应用则会出现因鉴权失败无法拉取的情况。
- 免密插件默认覆盖ACK中所有命名空间中默认的ServiceAccount中的imagePullSecret字段。被覆盖的 ServiceAccount会随着对应kube-system命名空间中acr-configuration配置项中的service-account字段变动而变动。
- 在修改kube-system命名空间中的acr-configuration配置项时，请确认缩进是否与给出的场景的例子相同。建议直接复制对应场景的YAML内容到编辑器中，修改对应的值然后直接应用到集群，以保证YAML格式的正确性。
背景信息
使用免密组件涉及的镜像及集群限制如下：
- 镜像
- 支持拉取容器镜像服务企业版实例和个人版实例中的私有镜像。
- 支持拉取集群当前用户容器镜像服务中的私有镜像，通过跨账号授权或AccessKey ID和AccessKey Secret配置可以拉取其他用户的私有镜像。
- 支持跨地域拉取容器镜像服务中的私有镜像。
- 集群
- 支持集群多命名空间免密拉取。
- 支持的集群类型：
- 专有版Kubernetes集群。
- 托管版Kubernetes集群。
- 注册集群
- 支持的集群版本：
- 自建Kubernetes集群：高于或等于1.11.2的版本默认支持免密拉取镜像。
步骤一：在自建集群中配置免密组件RAM权限
在注册集群中安装组件前，您需要在接入集群中设置AK用来访问云服务的权限。设置AK前，您需要创建RAM用户并为其添加访问相关云资源的权限。
{ "Version": "1", "Statement": [ { "Action": [ "cr:GetAuthorizationToken", "cr:ListInstanceEndpoint", "cr:PullRepository" ], "Resource": [ "*" ], "Effect": "Allow" } ] }
- 为RAM用户添加权限。有关如何为RAM用户授权的具体步骤，请参见为RAM用户授权。
- 为RAM用户创建AK。有关如何为子账户创建AK，请参见获取AccessKey。
- 使用AK在自建Kubernetes集群中创建名为alibaba-addon-secret的Secret资源，步骤二中安装事件中心相关组件时将自动引用此AK访问对应的云服务资源。
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>'
您需要将上述代码中和替换为您获取的AK信息。
步骤二：升级组件并对组件进行配置
在使用免密组件拉取镜像前，您可能需要升级组件并对组件进行配置，操作步骤如下。
- 升级aliyun-acr-credential-helper组件。
- 登录容器服务管理控制台。
- 在控制台左侧导航栏中，单击集群。
- 在集群列表页面，单击目标集群操作列下的更多 > 系统组件管理。
- 在安全区域，找到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: cri-xxx regionId: cn-hangzhou domains: xxx.com,yyy.com 针对默认版容器镜像实例，配置示例如下：
- instanceId: "" regionId: cn-hangzhou domains: xxx.com,yyy.com |
| watch-namespace | 期望能免密拉取镜像的Namespace。 | 默认值为Default。 说明 当取值为ALL时，表示期望所有Namespace都能免密拉取。如果需要配置多个Namespace时，以逗号分隔。 |
| expiring-threshold | 本地Cache Token过期阈值。 | 默认值为15m（建议使用15 m）。 |
- 通过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
场景一：拉取个人版实例和企业实例的私有镜像
ACK支持同时拉取企业版和个人版的私有镜像，只拉取企业版的私有镜像，只拉取个人版的私有镜像。根据您的使用场景，按照以下方式修改配置项acr-configuration中的configMap。配置步骤请参见上述配置组件。以下为配置内容：
- 配置拉取企业版的私有镜像。
data: service-account: "default" watch-namespace: "all" expiring-threshold: "15m" notify-email: "cs@aliyuncs.com" acr-registry-info: | - instanceId: "cri-xxx" regionId: "cn-hangzhou" domains: "xxx.com","yyy.com"
- 配置拉取个人版的私有镜像。
data: service-account: "default" watch-namespace: "all" expiring-threshold: "15m" notify-email: "cs@aliyuncs.com" acr-registry-info: | - instanceId: "" regionId: "cn-hangzhou" domains: "xxx.com","yyy.com"
- 配置同时拉取个人版和企业版的私有镜像。
data: service-account: "default" watch-namespace: "all" expiring-threshold: "15m" notify-email: "cs@aliyuncs.com" acr-registry-info: | - instanceId: "" - instanceId: "cri-xxxx"
场景二：配置跨地域拉取镜像权限
如果需要拉取的镜像与当前ACK集群不属于同一地域的时候，需要修改配置项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
