使用aliyun-acr-credential-helper组件,您可以配置ACK集群,以便在拉取经济版或企业版私有镜像时自动获取访问凭据,无需手动提供用户名和密码,以实现在阿里云容器服务ACK集群中实现免密拉取容器镜像服务ACR私有镜像。
前提条件
使用说明
免密组件通过读取ACK集群内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格式的正确性。 |
步骤一:安装免密组件
如果您已安装免密组件,请确保该组件为最新版本。否则,请升级该组件。此组件升级不会对业务造成影响。具体操作,请参见管理组件。关于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进行配置。
通过控制台配置
通过kubectl命令行配置
执行以下命令,打开acr-configuration配置项的编辑页。
kubectl edit cm acr-configuration -n kube-system
根据实际情况设置acr-configuration配置项的值。
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时,以英文半角逗号(,)分隔。
说明推荐配置生效Namespace为您的业务Namespace,尽量避免配置all或者集群系统组件相关Namespace,以免影响集群系统组件镜像的拉取。
expiring-threshold
本地缓存凭证过期阈值。
默认值为15m。
说明建议使用15min。即在缓存过期15分钟前进行凭证更新。
步骤三:根据实际场景配置拉取镜像
不同场景下,私有镜像拉取权限的配置方式不同。
配置策略 | 适用场景 | |
默认拉取策略,适用于同账号场景。 | ||
跨地域场景。 | ||
使用RRSA进行跨账号拉取镜像 | 跨账号场景。 | |
使用角色扮演进行跨账号拉取镜像 |
| |
使用RAM用户(子账号)的AccessKey ID和AccessKey Secret进行跨账号拉取镜像 | 跨账号场景。 使用RAM用户的AK(AccessKey ID)和SK(AccessKey Secret)进行镜像拉取时,需要将访问密钥写入ConfigMap,此方式存在一定的密钥泄露风险。请确保AccessKey ID和AccessKey Secret所属的RAM角色仅拥有拉取容器镜像的相关权限。推荐使用其他两种跨账号拉取方式。 |
您可以根据实际场景需要,选择以下三种场景中对应的场景进行配置。
场景一:配置同账号拉取镜像
创建自定义权限策略,策略内容如下。具体操作,请参见步骤一:创建自定义权限策略。
{ "Version": "1", "Statement": [ { "Action": [ "cr:GetAuthorizationToken", "cr:ListInstanceEndpoint", "cr:PullRepository" ], "Resource": "*", "Effect": "Allow" } ] }
为集群的Worker RAM角色授权。具体操作,请参见步骤二:为集群的Worker RAM角色授权。
设置acr-configuration配置项,即修改acr-configuration配置项中ConfigMap的配置,用于拉取企业版的私有镜像。
data: service-account: "default" watch-namespace: "all" expiring-threshold: "15m" notify-email:"c*@aliyuncs.com" acr-registry-info:| - instanceId: "cri-instanceId" regionId: "cn-hangzhou" domains: "instance.default.domain.com,instance.custom.domain.com"
场景二:配置跨地域拉取镜像
如需拉取的镜像与当前ACK集群不属于同一地域时,您需要修改配置项acr-configuration中的ConfigMap。
开启跨地域拉取镜像后,免密组件将通过公网调用目标地域的OpenAPI,集群必须具有出公网能力。
例如,默认仓库同时拉取北京地域与杭州地域的镜像时,需要按照以下内容,修改acr-configuration配置项中ConfigMap的配置。
data:
service-account: "default"
watch-namespace: "all"
expiring-threshold: "15m"
notify-email:"c*@aliyuncs.com"
acr-registry-info: |
- instanceId: "cri-instanceId"
regionId: "cn-beijing"
- instanceId: "cri-instanceId"
regionId: "cn-hangzhou"
场景三:配置跨账号拉取镜像
您可以通过以下三种方式进行跨账号拉取镜像。
使用RRSA进行跨账号拉取:A用户扮演B用户的角色拉取B用户的私有镜像。
使用角色扮演进行跨账号拉取:A用户扮演B用户的角色拉取B用户的私有镜像。
使用RAM用户(子账号)的AK及SK进行跨账号拉取:A用户使用B用户的子账号拉取B用户的私有镜像。
使用RRSA进行跨账号拉取
基于适用于服务账户的RAM角色(RAM Roles for Service Accounts,简称RRSA)功能,可以在集群内为组件实现Pod维度的权限隔离。
RRSA功能目前仅支持在1.22及以上版本的集群(即ACK标准版、ACK Pro版、ACK Serverless集群基础版和ACK Serverless集群Pro版)中拉取ACR企业版实例(基础版,标准版,高级版)的镜像。
开启RRSA功能需要将组件升级到v23.02.06.1-74e2172-aliyun或以上版本。
启用免密插件的RRSA功能首先需要在集群基本信息中启用RRSA,再进行免密插件RRSA的相关配置。若操作顺序颠倒,在配置完成后,则需要删除免密插件的Pod,RRSA功能才会生效。
启用集群的RRSA功能。具体操作,请参见启用RRSA功能。
配置跨账号RAM用户的容器镜像服务资源访问权限。
集群开启RRSA功能后,需要按照以下步骤进行配置。假设A用户为集群所有者,B用户为容器镜像服务实例所有者,现在需要授权A用户的集群具备访问B用户容器镜像服务资源的权限。
配置A用户的RAM角色
在A用户中创建一个角色,添加AliyunSTSAssumeRoleAccess权限策略,授予这个角色具有角色扮演的权限。按照如下修改其信任策略。
将示例中的<oidc_issuer_url>替换为当前集群中OIDC提供商的URL。该URL可在容器服务管理控制台集群信息页面的基本信息页签获取。
将示例中的<oidc_provider_arn>替换为当前集群OIDC提供商的ARN。该ARN可在容器服务管理控制台集群信息页面的基本信息页签获取。
{ "Statement": [ { "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "oidc:aud": "sts.aliyuncs.com", "oidc:iss": "<oidc_issuer_url>", "oidc:sub": "system:serviceaccount:kube-system:aliyun-acr-credential-helper" } }, "Effect": "Allow", "Principal": { "Federated": [ "<oidc_provider_arn>" ] } } ], "Version": "1" }
配置B用户的RAM角色
在B用户中创建一个拥有ACR相关权限的角色,选择信任策略管理,添加A用户角色ARN。
{ "Statement": [ { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "RAM": [ <A用户创建角色的ARN> ] } } ], "Version": "1" }
然后对B用户的角色添加如下权限策略,授予这个角色获取实例信息及拉取镜像权限。
{ "Version": "1", "Statement": [ { "Action": [ "cr:GetAuthorizationToken", "cr:ListInstanceEndpoint", "cr:PullRepository" ], "Resource": "*", "Effect": "Allow" } ] }
该RAM角色可以设置角色最大会话时间,可设置时间范围为3600秒到43200秒,而角色会话时间在下文的配置项中的expireDuration也需要设置。推荐此处取值的设置和配置项的expireDuration的值一致。允许expireDuration小于等于角色最大会话时间。
设置acr-configuration配置项
按照如下配置内容,修改acr-configuration配置项中ConfigMap的配置。
data: rrsa: | enable: true acr-registry-info: | - instanceId: cri-xxx regionId: cn-hangzhou rrsaRoleARN: aUserRoleARN rrsaOIDCProviderRoleARN: aUserClusterOIDCProviderRoleARN assumeRoleARN: bUserRoleARN expireDuration: 3600
配置项键
配置项说明
配置项值
rrsaRoleARN
上文中A用户创建的角色的ARN。
acs:ram::aaa
rrsaOIDCProviderRoleARN
上文中A用户ACK控制台集群基本信息中的提供商ARN。
acs:ram::bbb
assumeRoleARN
上文中B用户创建的角色的ARN。
acs:ram::ccc
expireDuration
上文中B用户创建的角色的会话时间,等同于免密组件生成的临时凭证的有效期。
重要expireDuration的值不应大于B用户创建角色的最大会话时间。
默认为3600。取值范围为[3600, 43200],单位为秒。
同时需要将B用户创建角色的最大会话时间调整为43200。
使用角色扮演进行跨账号拉取
使用RAM用户(子账号)的AK及SK进行跨账号拉取
常见问题
如何拉取个人版实例中的私有镜像
针对个人版迁移到企业版过程中需要在过渡阶段同时拉取企业版实例及个人版实例私有镜像的场景,您需要按照如下配置示例修改acr-configuration
配置项。若您想使用个人版实例推送拉取镜像,请参见使用个人版实例推送拉取镜像。
修改acr-configuration配置项前,请删除#-instanceId
值中的#
。
data:
service-account: "default"
watch-namespace: "all"
expiring-threshold: "15m"
notify-email:"cs@aliyuncs.com"
acr-registry-info: |
- instanceId: ""
regionId: cn-xxxx
如何开启ServiceAccount创建即时使用功能
启用Webhook功能后,ServiceAccount在创建时会即时注入Secret,满足特定场景下ServiceAccount无延迟注入Secret的需求。例如,通过Helm Chart同时创建ServiceAccount和Deployment的场景,其他场景不推荐开启该功能。
开启ServiceAccount创建即时使用功能需要将免密组件升级到v23.02.06.1-74e2172-aliyun或以上版本。
免密组件升级为最新版本后,您需要按照如下配置示例修改acr-configuration配置项。
data:
webhook-configuration: |
enable: true
failure-policy: Ignore
timeout-seconds: 10
表 1. 配置项说明
配置项键 | 配置项键说明 | 配置项值 |
enable | 是否开启本功能。 | 可选true或false。默认为false,即不开启。 |
failure-policy | 当本功能出现异常时的失败处理策略。 | 可选Ignore或Fail。
受集群APIServer的限制,当timeout-seconds设置为15,failure-policy设置为Fail,持续每秒创建10个ServiceAccount时,会出现超时创建ServiceAccount失败的情况。 |
timeout-seconds | 本功能的单个ServiceAccount创建请求处理超时时长,超出该时长则按照failure-policy配置进行反馈。 | 默认为 10,单位为秒(配置项值无需填写单位)。 |