K8s场景如何免密拉取ACR镜像 - 容器服务 Kubernetes 版 ACK

背景信息

阿里云容器镜像服务ACR分为个人版和企业版。其中，企业版是企业级云原生应用制品管理平台，提供容器镜像、Helm Chart以及符合OCI规范制品的生命周期管理，适用于业务大规模部署场景，帮助企业降低交付复杂度。更多信息，请参见容器镜像服务ACR简介。

创建ECI实例或镜像缓存时，如果要拉取的镜像属于ACR镜像，可以配置免密来简化流程，提升效率，同时避免密码泄露的风险，加强安全性。

说明

非ACR镜像（例如Docker镜像）不支持免密。

前提条件

配置ECI实例等资源免密拉取ACR镜像前，请确保您已经完成以下操作：

已创建ACR实例，并完成镜像仓库、镜像等相关配置。
- 关于如何配置ACR个人版实例，请参见使用个人版实例推送拉取镜像。
- 关于如何配置ACR企业版实例，请参见使用企业版实例推送和拉取镜像。
如果使用ACR企业版实例，需要配置免密访问。

新创建的ACR企业版实例默认处于非连接状态，需要配置相应的ACL策略后，才可以通过公网或者专有网络访问该实例。
- 公网访问：开启公网访问入口后，可以直接通过公网域名地址来访问ACR企业版实例的镜像（可跨域）。具体操作，请参见配置公网的访问控制。
- 专有网络访问：使用专有网络VPC访问ACR企业版实例，需要开启相关授权。具体操作，请参见配置专有网络的访问控制。

配置说明

对于ACR镜像，根据ACR实例是否与待创建的ECI实例等资源属于同一阿里云账号，以及ACR实例的类型，免密拉取镜像的支持情况如下：

账号情况	ACR类型	免密支持情况
同账号	个人版企业版（默认域名）	默认自动免密，支持配置RAM角色来限制免密范围。
同账号	企业版（自定义域名）	无法自动免密，需要指定ACR实例来实现免密。
跨账号	个人版企业版	无法自动免密，需要配置RAM角色来实现免密。

请根据您的账号和ACR实例情况选择对应的配置。

指定RAM角色以限制免密范围

在ACR实例与待创建的ECI实例等资源属于同一阿里云账号的前提下，如果ACR实例是个人版ACR，或者是使用默认域名的企业版ACR，则默认自动免密。此时，您可以按需配置RAM角色来限制免密范围，例如只允许某一ACR实例自动免密。

说明

默认情况下，ECI使用服务关联角色AliyunServiceRoleForECI来获取其他云服务的访问权限，以便创建ECI资源，该角色包含了拉取ACR镜像的权限，适用于同账号下的所有个人版ACR和使用默认域名的企业版ACR，无法进行细粒度控制。

配置步骤包含以下两步。

步骤一：创建RAM角色并授权

创建一个可信实体为阿里云服务的RAM角色。具体操作，请参见创建可信实体为阿里云服务的RAM角色。

需要注意的配置项如下：
- 信任主体类型：云服务
- 信任主体名称：弹性容器实例ECI
- 角色名称：示例为acr-test

创建自定义权限策略。具体操作，请参见创建自定义权限策略。

权限策略的内容示例如下，表示只允许拉取指定ACR实例的镜像。关于如何编写权限策略，请参见权限策略基本元素。

{
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cr:Get*",
                "cr:List*"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "cr:Pull*"
            ],
            "Resource": [
                "acs:cr:cn-hangzhou:1609982529******:instance/cri-nwj395hgf6f3****"
            ]
        }
    ]
}

为RAM角色绑定自定义权限策略。具体操作，请参见管理RAM角色的权限。
找到新创建的acr-test角色，单击角色名称进入详情页面，确认权限并获取ARN。

在基本信息区域找到 ARN 字段（格式为 acs:ram::<AccountID>:role/acr-test），单击右侧复制按钮复制该值。在 权限管理 页签下，确认已关联自定义策略 acr。

步骤二：指定RAM角色

创建ECI Pod和ImageCache时，您可以添加Annotation（k8s.aliyun.com/acr-service-arns）来指定创建资源时使用的RAM角色。

以创建ECI Pod为例，YAML如下：

重要

Annotation请添加在Pod的metadata下，例如：创建Deployment时，Annotation需添加在spec>template>metadata下。
仅支持在创建ECI Pod时添加ECI相关Annotation来生效ECI功能，更新ECI Pod时添加或者修改ECI相关Annotation均不会生效。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true" 
      annotations:                  
        k8s.aliyun.com/acr-service-arns: "acs:ram::1609982529******:role/acr-test" #指定使用的RAM角色
    spec:
      containers:
      - name: nginx
        image: test****-registry.cn-hangzhou.cr.aliyuncs.com/eci_test/nginx:1.0   #镜像需属于RAM角色允许的ACR实例
        ports:
        - containerPort: 80

指定ACR实例来配置ACR企业版免密

在ACR实例与待创建的ECI实例属于同一阿里云账号的前提下，如果ACR企业版实例使用自定义域名，则需要指定ACR企业版实例来配置免密。配置方式为添加k8s.aliyun.com/acr-instance-ids的Annotation来指定ACR实例ID。

说明

ACR企业版实例支持跨地域使用，即指定的ACR企业版实例与Pod的所属地域可以不同。指定时，需在ACR实例ID前加上所属地域，例如cn-beijing:cri-j36zhodptmyq****。

创建ECI Pod

创建ECI Pod时，您可以在Pod metadata中添加Annotation（k8s.aliyun.com/acr-instance-ids）来指定ACR实例。

重要

Annotation请添加在Pod的metadata下，例如：创建Deployment时，Annotation需添加在spec>template>metadata下。
仅支持在创建ECI Pod时添加ECI相关Annotation来生效ECI功能，更新ECI Pod时添加或者修改ECI相关Annotation均不会生效。

配置示例如下：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true" 
      annotations:
        k8s.aliyun.com/acr-instance-ids: "cri-j36zhodptmyq****"      #指定ACR实例ID
    spec:
      containers:
      - name: nginx
        image: test****-registry.example.com/eci_test/nginx:1.0   #指定使用自定义域名的ACR企业版镜像
        ports:
        - containerPort: 80

创建ImageCache

创建ImageCache时，您可以在ImageCache的metadata中添加Annotation（k8s.aliyun.com/acr-instance-ids）来指定ACR实例。配置示例如下：

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/acr-instance-ids: "cri-j36zhodptmyq****" #指定ACR实例ID
spec:
  images: 
  - test****-registry.example.com/eci_test/nginx:1.0   #指定使用自定义域名的ACR企业版镜像
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3
  imageCacheSize:
   25
  retentionDays:
   7

授权RAM角色来配置跨账号免密

如果ACR实例与待创建的ECI实例不属于同一阿里云账号，则需要分别在两个账号下配置RAM角色并完成授权后，才能实现免密。

配置步骤包含以下两步：

步骤一：创建RAM角色并授权

在ECI实例等资源归属账号A下创建RAM角色并授权。
1. 创建一个可信实体为阿里云服务的RAM角色。具体操作，请参见创建可信实体为阿里云服务的RAM角色。
  
  需要注意的配置项如下：
  - 信任主体类型：云服务
  - 信任主体名称：弹性容器实例ECI
  - 角色名称：示例为role-assume
2. 为role-assume角色授予调用STS服务AssumeRole接口的权限。具体操作，请参见为RAM角色精确授权。
  
  要添加的权限类型为系统策略，权限策略名称为AliyunSTSAssumeRoleAccess。
3. 找到新创建的role-assume角色，单击角色名称进入详情页面，确认权限和信任策略，并获取ARN。
  - 权限和ARN
    
    RAM角色的ARN为 acs:ram::<账号ID>:role/role-assume，已授予系统策略 AliyunSTSAssumeRoleAccess（用于调用STS服务AssumeRole接口）。
  - 信任策略
```
{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "eci.aliyuncs.com"
        ]
      }
    }
  ],
  "Version": "1"
}
```
在ACR实例归属账号B下创建RAM角色并授权。
1. 创建一个可信实体为阿里云账号的RAM角色。具体操作，请参见创建可信实体为阿里云账号的RAM角色。
  
  需要注意的配置项如下：
  - 信任主体类型：云账号
  - 信任主体名称：其他云账号，此处填写ECI实例等资源归属账号A
  - 角色名称：示例为role-acr
2. 为role-acr角色授予拉取ACR镜像的权限。具体操作，请参见为RAM角色精确授权。
  
  要添加的权限类型为系统策略，权限策略名称为AliyunContainerRegistryFullAccess。
3. 修改信任策略，将role-acr角色授信给role-assume角色。具体操作，请参见修改RAM角色的信任策略。
  
  默认情况下，role-acr角色可以被账号A下授权的任何RAM用户或RAM角色扮演。建议您修改信任策略进行精确授信。
  
  在Principal处，将RAM字段的值改为role-assume角色的ARN，则表示role-acr角色只可以被role-assume角色扮演。示例如下：
```
"Principal": {
	"RAM": [
		"acs:ram::1609982529******:role/role-assume"
	]
}
```
4. 确认权限和信任策略，并获取ARN。
  - 权限和ARN
    
    角色 role-acr 的 ARN 为 acs:ram::<账号ID>:role/role-acr，单击旁边的复制按钮可复制该值。在权限管理页签中确认已授予 AliyunContainerRegistryFullAccess 系统策略，资源范围为账号级别。
  - 信任策略
```
{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": ["acs:ram::10051309xxxx:role/role-assume"]
      }
    }
  ],
  "Version": "1"
}
```

步骤二：指定RAM角色创建资源

创建ECI Pod和ImageCache时，您可以添加Annotation来指定其他阿里云账号下的ACR实例拉取镜像。相关注意事项如下：

如果ACR实例属于其他阿里云账号，则必须添加k8s.aliyun.com/acr-service-arns和k8s.aliyun.com/acr-user-arns两个Annotation来指定RAM角色，以配置权限。
- k8s.aliyun.com/acr-service-arns：ECI资源归属账号下的RAM角色的ARN。
- k8s.aliyun.com/acr-user-arns：ACR实例归属账号下的RAM角色的ARN。
如果ACR实例为使用自定义域名的企业版实例，则必须添加k8s.aliyun.com/acr-instance-ids的Annotation来指定ACR实例。
说明
ACR企业版实例支持跨地域使用，即指定的ACR企业版实例与Pod的所属地域可以不同。指定时，需在ACR实例ID前加上所属地域，例如cn-beijing:cri-j36zhodptmyq****。

创建ECI Pod

创建ECI Pod时，您可以在Pod metadata中添加以下Annotation来指定其他阿里云账号下的ACR实例：

annotations:
    k8s.aliyun.com/acr-instance-ids: "cri-j36zhodptmyq****" 
    k8s.aliyun.com/acr-service-arns: "acs:ram::1609982529******:role/role-assume"
    k8s.aliyun.com/acr-user-arns: "acs:ram::1298452580******:role/role-acr"

重要

Annotation请添加在Pod的metadata下，例如：创建Deployment时，Annotation需添加在spec>template>metadata下。
仅支持在创建ECI Pod时添加ECI相关Annotation来生效ECI功能，更新ECI Pod时添加或者修改ECI相关Annotation均不会生效。

完整YAML示例如下：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true" 
      annotations:
        k8s.aliyun.com/acr-instance-ids: "cri-j36zhodptmyq****"                        
        k8s.aliyun.com/acr-service-arns: "acs:ram::1609982529******:role/role-assume"
        k8s.aliyun.com/acr-user-arns: "acs:ram::1298452580******:role/role-acr"
    spec:
      containers:
      - name: nginx
        image: test****-registry.example.com/eci_test/nginx:1.0   #指定使用自定义域名的ACR企业版镜像
        ports:
        - containerPort: 80

创建ImageCache

创建ImageCache时，您可以在ImageCache的metadata中添加以下Annotation来指定其他阿里云账号下的ACR实例：

annotations:
    k8s.aliyun.com/acr-instance-ids: "cri-j36zhodptmyq****"
    k8s.aliyun.com/acr-service-arns: "acs:ram::1609982529******:role/role-assume"
    k8s.aliyun.com/acr-user-arns: "acs:ram::1298452580******:role/role-acr"

完整YAML示例如下：

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/acr-instance-ids: "cri-j36zhodptmyq****"
    k8s.aliyun.com/acr-service-arns: "acs:ram::1609982529******:role/role-assume"
    k8s.aliyun.com/acr-user-arns: "acs:ram::1298452580******:role/role-acr"
spec:
  images: 
  - test****-registry.example.com/eci_test/nginx:1.0   #指定使用自定义域名的ACR企业版镜像
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3
  imageCacheSize:
   25
  retentionDays:
   7