通过aliyun-acr-credential-helper组件可以在自建Kubernetes集群中免密拉取ACR个人版或企业版私有镜像。本文列举两个场景介绍如何使用免密组件拉取私有镜像。
前提条件
已创建注册集群,并将自建Kubernetes集群接入注册集群。具体操作,请参见通过控制台创建注册集群、通过onectl创建注册集群。
已通过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进行配置。
通过控制台配置
通过kubectl命令行配置
执行以下命令,打开acr-configuration配置项的编辑页。
kubectl edit cm acr-configuration -n kube-system
根据实际情况设置acr-configuration配置项的值。
acr-configuration配置项的键和值说明如下。
配置项键
配置项键说明
配置项值
service-account
将免密认证机制应用于指定的服务账户。
说明服务账户(ServiceAccount)是指定给运行在Kubernetes集群内的服务和应用的身份标识。
默认为default。
说明如果要配置多个请以英文半角逗号(,)分隔, 如果设置为
“*”
, 表示支持指定命名空间下的所有ServiceAccount。acr-registry-info
容器镜像的实例信息数组,YAML多行字符串格式,每个实例以三元组方式配置。
说明实例信息三元组:
instanceId:实例ID,企业版实例必须配置此项。若要确保个人版正常使用,须在控制台将YAML配置中的
#-instanceId
前的#
删除以激活该项。regionId:可选,默认为本地地域。
domains:可选,默认为相应实例的所有域名。若要指定个别域名,多个以英文半角逗号(,)分隔。
默认值为空,表示免密拉取同地域的个人版实例镜像(兼容场景)。
针对企业版容器镜像实例,配置示例如下:
- instanceId: <cri-instanceId> regionId: "cn-hangzhou" domains: "xxx.com,yyy.com"
watch-namespace
期望能免密拉取镜像的Namespace。
默认值为default。当取值为all时,表示期望所有Namespace均能免密拉取。如需配置多个Namespace时,以英文半角逗号(,)分隔。
说明推荐配置生效Namespace为您的业务Namespace,尽量避免配置all或者集群系统组件相关Namespace,以免影响集群系统组件镜像的拉取。
expiring-threshold
本地缓存凭证过期阈值。
默认值为15m。
说明建议使用15min。即在缓存过期15分钟前进行凭证更新。
场景一:拉取个人版实例和企业实例的私有镜像
注册集群支持同时拉取企业版和个人版的私有镜像,只拉取企业版的私有镜像,只拉取个人版的私有镜像。根据您的使用场景,按照以下方式修改配置项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配置项的值。