若您想使用个人版实例推送拉取镜像，请参见使用个人版实例推送拉取镜像。

前提条件

使用说明

注意事项

步骤一：安装免密组件

步骤二：根据实际场景配置拉取镜像

场景一：配置同账号拉取镜像

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

场景三：配置跨账号拉取镜像

其他功能

相关文档

已创建Kubernetes托管版集群

已获取集群KubeConfig并通过kubectl工具连接集群

免密组件通过读取ACK集群内kube-system命名空间中acr-configuration的配置，进行私有镜像拉取。免密组件配置完成后将会在集群中自动创建Secret，并关联到配置中已指定的ServiceAccount。任何使用此ServiceAccount的Pod都会默认使用免密组件生成的Secret进行镜像拉取，从而实现免密拉取镜像的效果。

针对新创建ServiceAccount部署应用的场景（例如部署Helm Chart），免密组件ServiceAccount关联Secret可能存在延迟，建议使用Webhook功能。更多信息，请参见其他功能。

免密组件拉取私有镜像的使用条件如下。

类别

说明

镜像

支持拉取集群当前RAM用户容器镜像服务中的私有镜像。

支持通过跨账号授权或AccessKey ID和AccessKey Secret配置的方式，拉取其他RAM用户的私有镜像。

支持拉取容器镜像服务企业版实例中的私有镜像。

集群及版本

支持的集群类型：

专有版Kubernetes集群：大于或等于1.11.2的版本默认支持免密拉取镜像。低于1.11.2版本请您手动升级，请参见手动升级集群。

托管版Kubernetes集群：所有版本。

支持集群多命名空间免密拉取。

类别

注意事项

拉取凭证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格式的正确性。

如果您已安装免密组件，请确保该组件为最新版本。否则，请升级该组件。此组件升级不会对业务造成影响。具体操作，请参见管理组件。关于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进行配置。

登录容器服务管理控制台，在左侧导航栏选择集群。

在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择配置管理 > 配置项。

在配置项页面顶部的命名空间下拉列表，选择kube-system，然后找到配置项acr-configuration，设置配置项的值。

如果您没有acr-configuration配置项，请参见创建配置项。关于如何更新配置项，请参见修改配置项。

单击其右侧的编辑，设置配置项键和值。

单击其右侧的YAML编辑，设置配置项键和值。

执行以下命令，打开acr-configuration配置项的编辑页。

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

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

配置项键

配置项键说明

配置项值

service-account

使免密组件作用于指定的服务账号。

默认为default。

如果要配置多个请以英文半角逗号（,）分隔， 如果设置为“*”， 表示支持指定命名空间下的所有ServiceAccount。

acr-registry-info

容器镜像的实例信息数组，YAML多行字符串格式，每个实例以三元组方式配置。

实例信息三元组：

instanceId：实例ID，企业版实例必须配置此项。

regionId：可选，默认为本地地域。

domains：可选，默认为相应实例的所有域名。若要指定个别域名，多个以英文半角逗号（,）分隔。

企业版容器镜像实例，配置示例如下：

watch-namespace

期望能免密拉取镜像的Namespace。

默认值为default。当取值为all时，表示期望所有Namespace均能免密拉取。如需配置多个Namespace时，以英文半角逗号（,）分隔。

推荐配置生效Namespace为您的业务Namespace，尽量避免配置all或者集群系统组件相关Namespace，以免影响集群系统组件镜像的拉取。

expiring-threshold

本地缓存凭证过期阈值。

默认值为15m。

建议使用15min。即在缓存过期15分钟前进行凭证更新。

不同场景下，私有镜像拉取权限的配置方式不同。

配置策略

适用场景

场景一：配置同账号拉取镜像

默认拉取策略，适用于同账号场景。

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

跨地域场景。

场景三：配置跨账号拉取镜像

使用RRSA进行跨账号拉取镜像

跨账号场景。

使用角色扮演进行跨账号拉取镜像

依赖Worker Role的集群。

跨账号场景。

使用RAM用户（子账号）的AccessKey ID和AccessKey Secret进行跨账号拉取镜像

跨账号场景。

使用RAM用户的AK（AccessKey ID）和SK（AccessKey Secret）进行镜像拉取时，需要将访问密钥写入ConfigMap，此方式存在一定的密钥泄露风险。请确保AccessKey ID和AccessKey Secret所属的RAM角色仅拥有拉取容器镜像的相关权限。推荐使用其他两种跨账号拉取方式。

您可以根据实际场景需要，选择以下三种场景中对应的场景进行配置。

创建自定义权限策略，策略内容如下。具体操作，请参见步骤一：创建自定义权限策略。

为集群的Worker RAM角色授权。具体操作，请参见步骤二：为集群的Worker RAM角色授权。

设置acr-configuration配置项，即修改acr-configuration配置项中ConfigMap的配置，用于拉取企业版的私有镜像。

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

开启跨地域拉取镜像后，免密组件将通过公网调用目标地域的OpenAPI，集群必须具有出公网能力。

例如，默认仓库同时拉取北京地域与杭州地域的镜像时，需要按照以下内容，修改acr-configuration配置项中ConfigMap的配置。

您可以通过以下三种方式进行跨账号拉取镜像。

使用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提供商的URL。该URL可在容器服务管理控制台集群信息页面的基本信息页签获取。

将示例中的替换为当前集群OIDC提供商的ARN。该ARN可在容器服务管理控制台集群信息页面的基本信息页签获取。

配置B用户的RAM角色

在B用户中创建一个拥有ACR相关权限的角色，选择信任策略管理，添加A用户角色ARN。对B用户的角色添加如下权限策略，授予这个角色具有获取实例信息及拉取镜像权限。

该RAM角色可以设置角色最大会话时间，可设置时间范围为3600秒到43200秒，而角色会话时间在下文的配置项中的expireDuration也需要设置。推荐此处取值的设置和配置项的expireDuration的值一致。允许expireDuration小于等于角色最大会话时间。

设置acr-configuration配置项

按照如下配置内容，修改acr-configuration配置项中ConfigMap的配置。

配置项键

配置项说明

配置项值

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。

使用角色扮演进行跨账号拉取

展开查看如何使用角色扮演进行跨账号拉取

配置原则如下：

B用户（RAM角色）可以拉取指定私有仓库下的私有镜像（B用户RAM角色有cr.*相关的权限）。

B用户（RAM角色）允许让A用户下的ACK Worker RAM角色扮演（信任策略）。

A用户下的ACK集群的Worker RAM角色有扮演B用户（RAM角色）的权限（AliyunAssumeRoleAccess）。

设置A用户下的Worker RAM角色扮演B用户（configMap中的assumeRoleARN）。

创建B用户的受信实体为阿里云账号类型的RAM角色，并确保该RAM角色拥有拉取B用户私有镜像的权限。

创建RAM角色。

具体操作请参见创建可信实体为阿里云账号的RAM角色。

自定义RAM角色权限策略内容，确保该RAM角色拥有拉取B用户私有镜像的权限。

具体操作请参见改自定义权限策略内容和备注。

请确保该RAM角色有cr.*的相关权限。

添加字段位置如下图所示。

在创建的B用户的RAM角色上配置信任策略，允许A用户（需要拉取B用户下的私有镜像）的ACK集群的Worker RAM角色来扮演B用户。

查看A用户的ACK集群的Worker RAM角色的ARN信息。

查看ARN信息具体步骤，请参见如何查看RAM角色的ARN？。

配置信任策略。

在RAM控制台左侧导航栏，单击RAM角色管理，找到目标RAM角色并单击RAM角色名称。

在RAM角色基本信息页，单击信任策略管理页签，然后使用A用户的Worker RAM角色的ARN修改信任策略。

确认A用户的Worker RAM角色拥有AssumeRole权限。具体操作，请参见查看权限策略基本信息。

调整组件配置，新增assumeRoleARN配置。

配置内容为您在B用户下新建RAM角色的ARN。关于查看ARN信息的具体步骤，请参见如何查看RAM角色的ARN？。acr-configuration配置示例如下。

使用RAM用户（子账号）的AK及SK进行跨账号拉取

展开查看如何使用RAM用户（子账号）的AK及SK进行跨账号拉取

创建一个RAM用户并为该用户添加cr镜像拉取权限。关于配置cr镜像拉取权限的具体操作，请参见场景三：配置跨账号拉取镜像。

配置kube-system命名空间中的配置项acr-configuration，并填入创建的RAM用户的访问密钥AccessKey ID和AccessKey Secret。

此方式可以使免密组件直接使用创建的RAM用户拉取私有镜像。查看访问密钥的具体步骤，请参见查看RAM用户的AccessKey信息。

acr-configuration配置示例如下。

针对个人版迁移到企业版过程中需要在过渡阶段同时拉取企业版实例及个人版实例私有镜像的场景，您需要按照如下配置示例修改acr-configuration配置项。

修改acr-configuration配置项前，请删除#-instanceId值中的#。

启用Webhook功能后，ServiceAccount在创建时会即时注入Secret，满足特定场景下ServiceAccount无延迟注入Secret的需求。例如，通过Helm Chart同时创建ServiceAccount和Deployment的场景，其他场景不推荐开启该功能。

开启ServiceAccount创建即时使用功能需要将免密组件升级到v23.02.06.1-74e2172-aliyun或以上版本。

免密组件升级为最新版本后，您需要按照如下配置示例修改acr-configuration配置项。

表 1. 配置项说明

配置项键

配置项键说明

配置项值

enable

是否开启本功能。

可选true或false。默认为false，即不开启。

failure-policy

当本功能出现异常时的失败处理策略。

可选Ignore或Fail。

Ignore即忽略异常，使ServiceAccount正常创建完成（但可能不会附上可拉取镜像的Secret）。

Fail即异常时中断创建ServiceAccount（不推荐，可能导致业务部署失败）。

受集群APIServer的限制，当timeout-seconds设置为15，failure-policy设置为Fail，持续每秒创建10个ServiceAccount时，会出现超时创建ServiceAccount失败的情况。

timeout-seconds

本功能的单个ServiceAccount创建请求处理超时时长，超出该时长则按照failure-policy配置进行反馈。

默认为 10，单位为秒（配置项值无需填写单位）。

aliyun-acr-credential-helper

通过RRSA配置ServiceAccount的RAM权限实现Pod权限隔离