文档

通过免密组件拉取容器镜像

更新时间:

通过aliyun-acr-credential-helper组件可以在自建Kubernetes集群中免密拉取ACR个人版或企业版私有镜像。本文列举两个场景介绍如何使用免密组件拉取私有镜像。

前提条件

使用说明

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

重要

针对新创建ServiceAccount部署应用的场景(例如部署Helm Chart),免密组件ServiceAccount关联Secret可能存在延迟,建议使用Webhook功能。

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

类别

说明

镜像

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

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

  • 支持拉取容器镜像服务企业版实例和个人版实例(兼容场景)中的私有镜像。

集群及版本

  • 集群版本不低于1.11.2。否则,请您手动升级。具体操作,请参见升级ACK集群

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

注意事项

类别

注意事项

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

在注册集群中配置免密组件

步骤一:为免密组件配置RAM权限

通过onectl配置

  1. 在本地安装配置onectl。具体操作,请参见通过onectl管理注册集群

  2. 执行以下命令,为免密组件配置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用户并为其添加访问相关云资源的权限。

  1. 创建RAM用户。具体操作,请参见创建RAM用户

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

    权限策略模板如下所示:

    {
        "Version": "1",
        "Statement": [
            {
                "Action": [
                    "cr:GetAuthorizationToken",
                    "cr:ListInstanceEndpoint",
                    "cr:PullRepository"
                ],
                "Resource": [
                    "*"
                ],
                "Effect": "Allow"
            }
        ]
    }
  3. 为RAM用户添加权限。具体操作,请参见为RAM用户授权

  4. 为RAM用户创建AccessKey。具体操作,请参见获取AccessKey

  5. 使用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组件依赖权限的公告

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

  2. 集群列表页面,单击目标集群名称,然后在左侧导航栏,选择运维管理 > 组件管理

  3. 组件管理页面,单击安全页签,找到aliyun-acr-credential-helper,单击安装

  4. 参数配置页面,组件使用的权限模式保持默认值auto,然后单击确定

    当ACK托管版集群升级到最新版本,aliyun-acr-credential-helper组件提供了tokenMode配置项,组件安装后也可以进行修改。组件修改后,Pod将会重建。2023年04月03日之前创建的集群为老集群,2023年04月03日及之后创建的集群为新集群。具体配置项内容如下。

    tokenMode

    说明

    auto

    默认值,表示自动确定是否使用managedRole。新集群使用managedRole模式,老集群使用workerRole模式。

    managedRole

    使用managedRole模式。

    workerRole

    使用workerRole模式。

  5. 免密组件安装完成后,在拉取镜像时,需要对免密组件配置项acr-configuration进行配置。

    通过控制台配置

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

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

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

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

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

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

    通过kubectl命令行配置

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

      kubectl edit cm acr-configuration -n kube-system
    2. 根据实际情况设置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配置项。

通过控制台配置

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

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

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

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

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

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

通过kubectl命令行配置

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

    kubectl edit cm acr-configuration -n kube-system
  2. 根据实际情况设置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配置项。

通过控制台配置

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

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

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

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

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

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

通过kubectl命令行配置

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

    kubectl edit cm acr-configuration -n kube-system
  2. 根据实际情况设置acr-configuration配置项的值。