使用免密组件拉取容器镜像

背景信息

免密组件通过读取ACK集群内的kube-system命名空间中的acr-configuration的配置，进行私有镜像拉取。当前支持针对私有镜像仓库使用以下三种权限之一的策略进行配置：

使用默认的ACK Worker RAM角色权限进行拉取（默认策略）。
使用自定义RAM角色的AccessKey ID和AccessKey Secret的权限进行拉取。
通过配置RAM AssumeRole权限，使用其他用户的权限进行拉取。

使用限制

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

镜像
- 支持拉取容器镜像服务企业版实例和个人版实例中的私有镜像。
- 支持拉取集群当前用户容器镜像服务中的私有镜像，通过跨账号授权或AccessKey ID和AccessKey Secret配置可以拉取其他用户的私有镜像。
- 支持跨地域拉取容器镜像服务中的私有镜像。
集群
- 支持集群多命名空间免密拉取。
- 支持的集群类型：
  - 专有版Kubernetes集群。
  - 托管版Kubernetes集群。
- 支持的集群版本：
  - 专有版Kubernetes集群：高于或等于1.11.2的版本默认支持免密拉取镜像。低于1.11.2版本请您手动升级，请参见升级ACK集群K8s版本。
  - 托管版Kubernetes集群：所有版本。

注意事项

在Kubernetes资源（例如无状态应用Deployment）模板中配置拉取凭证（imagePullSecret）会导致免密组件失效，如果需使用免密组件，请避免手工配置拉取凭证（imagePullSecret）。
如果部署的Kubernetes资源（例如无状态应用Deployment）使用了自定义的ServiceAccount，需先调整免密组件配置文件中Service-Account字段，使其作用于自定义的ServiceAccount，再进行部署资源操作。
确认Kubernetes集群所属地域与要拉取的镜像所在的地域是否一致，默认配置只可以拉取本地域的镜像。如果需要跨地域拉取镜像，请参见下面的场景三。
使用自定义RAM角色的AccessKey ID和AccessKey Secret进行镜像拉取的情况下，需要把访问密钥写入configMap，这样存在一定的密钥泄露风险。请确定AccessKey ID和AccessKey Secret所属的RAM角色只拥有拉取容器镜像的相关权限。
在集群中创建新的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格式的正确性。

升级并配置免密组件

在使用免密组件拉取镜像前，您可能需要升级组件并对组件进行配置，操作步骤如下。

升级aliyun-acr-credential-helper组件。
1. 登录容器服务管理控制台。
2. 在控制台左侧导航栏中，单击集群。
3. 在集群列表页面，单击目标集群操作列下的更多 > 系统组件管理。
4. 在安全区域，找到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-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 min）。

方式二：通过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"

场景二：配置当前账号拉取权限

您需要检查当前账号ACR拉取的权限。

登录容器服务管理控制台。
在控制台左侧导航栏中，单击集群。
在集群列表页面中，单击目标集群名称或者目标集群右侧操作列下的详情。
在集群信息页面，单击集群资源页签，单击Worker RAM角色右侧链接。
在RAM角色基本信息的权限管理页签，单击目标权限策略名称。
单击修改策略内容。

在策略内容区域增加以下字段后，单击确定。

{
  "Action": [
    "cr:Get*",
    "cr:List*",
    "cr:PullRepository"
  ],
  "Resource": "*",
  "Effect": "Allow"
}

说明您还需要检查Pod中镜像字段的值是否存在于ACR仓库里面。

如果存在，但不在当前账号下，您可能需要使用跨账号镜像拉取（具体操作，请参见场景四：配置跨账号拉取权限）。
如果存在，且在当前账号下，您可以提交工单。
如果不存在，您需要确认该镜像是否存在于阿里云容器镜像服务上。如果不存在，则需要同步外部镜像到阿里云容器镜像服务商，或者变更改镜像为公网可拉取状态。

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

如果需要拉取的镜像与当前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

场景四：配置跨账号拉取权限

跨账号拉取权限分为：

使用角色扮演进行跨账号拉取：A用户扮演B用户的角色拉取B用户的私有镜像。
使用自定义RAM角色的访问密钥进行跨账号私有镜像拉取：需要使用指定的用户的权限拉取特定的私有镜像。

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

说明

配置原则如下：

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用户私有镜像的权限。
1. 创建RAM角色。
  具体操作请参见创建可信实体为阿里云账号的RAM角色。
2. 自定义RAM角色权限策略内容，确保该RAM角色拥有拉取B用户私有镜像的权限。
  具体操作请参见修改自定义策略内容。
  注意请确保该RAM角色有cr.*的相关权限。
``` { "Action": [ "cr:GetAuthorizationToken", "cr:ListInstanceEndpoint", "cr:PullRepository" ], "Resource": [ "*" ], "Effect": "Allow" } ```
添加字段位置如下图所示。
在创建的B用户的RAM角色上配置信任策略，允许A用户（需要拉取B用户下的私有镜像）的ACK集群的Worker RAM角色来扮演B用户。
1. 查看A用户的ACK集群的Worker RAM角色的ARN信息。
  查看ARN信息具体步骤，请参见如何查看RAM角色的ARN？
2. 配置信任策略。
  1. 在RAM控制台左侧导航栏，单击RAM角色管理，找到目标RAM角色并单击RAM角色名称。
  2. 在RAM角色基本信息页，单击信任策略管理页签，然后使用A用户的Worker RAM角色的ARN修改信任策略。
确认A用户的Worker RAM角色拥有AssumeRole权限。
具体操作步骤，请参见查看权限策略基本信息。

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

配置内容为B用户Worker RAM角色的ARN。查看ARN信息具体步骤，请参见如何查看RAM角色的ARN？YAML配置示例如下。配置步骤，请参见上述配置组件。

data:
    service-account: "default"
    watch-namespace: "all"
    expiring-threshold: "15m"
    notify-email: "cs@aliyuncs.com"
    acr-registry-info: |
      - instanceId: ""
        regionId: cn-beijing
        domains: registry.cn-beijing.aliyuncs.com
        assumeRoleARN: acs:ram::.*:role/kubernetesworkerrole-test

使用RAM用户的访问密钥拉取跨账号私有镜像

创建一个RAM用户并为该用户添加cr镜像拉取权限。
有关配置cr镜像拉取权限的具体操作步骤，请参见使用角色扮演进行跨账号拉取步骤1。

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

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

配置示例如下。配置步骤请参见上述配置组件。

data:
    service-account: "default"
    watch-namespace: "all"
    expiring-threshold: "15m"
    notify-email: "cs@aliyuncs.com"
    acr-registry-info: |
      - instanceId: ""
        customAccessKey: "xxxxx" // 此处填写刚创建的RAM用户的AccessKey ID。
        customAccessKeySecret: "xxxxxx" // 此处填写刚创建的RAM用户的AccessKey Secret。