腾讯云 TKE 镜像更新插件

场景化封装腾讯云容器服务 API 实现工作负载 Deployment 、StatefulSet 类型的镜像更新操作

前置条件

使用的是腾讯云容器服务(TKE)集群,并且已经部署了对应 Deployment、StatefulSet 资源
访问集群用的腾讯云 secret_id 、secret_key, 并且已经设置好账号集群权限。设置方式见 doc/access.md

参数说明

secret_id 密钥 ID, 详情见 doc/access.md
secret_key 密钥 Key
region 集群地域, 格式如：ap-nanjing。详情见 doc/regions.md
cluster_id 集群ID, 格式如： cls-m9miwj4u
namespace 工作负载所在的集群命名空间, 如 default
workload_kind 工作负载类型. 支持 deployment、statefulset
workload_name 工作负载名称
container_names 容器名称, 如有多个用英文,分割
container_images 待更新的容器最新镜像, 如有多个用英文,分割
check_rollout_timeout (可选参数) 更新后监控 pod 滚动时间, 单位分钟, 整数. 设置为 0 则跳过等待
cloud_api_endpoint (可选参数) 腾讯云 API 请求地址. 默认为腾讯云基础网络内部地址。如有公网访问需求可配置为 tke.tencentcloudapi.com

TKE 集群拉取 CNB 镜像配置

当镜像推送至 CNB 的 Docker 仓库后，TKE 工作负载 Pod 拉取镜像时需要配置鉴权信息。

1. 创建访问凭证

前往 Docker image 所在仓库创建部署令牌（Deploy Token），注意勾选制品权限：

进入 CNB 项目的 设置 → 仓库设置 → 部署令牌
点击「生成部署令牌」，填写名称并勾选 read_registry 权限
保存生成的用户名和密码，后续用于创建 K8s Secret

2. 在 TKE 集群中配置 Secret 凭证

使用上一步生成的部署令牌，在目标 Namespace 中创建 kubernetes.io/dockerconfigjson 类型的 Secret：


kubectl create secret docker-registry cnb-registry-secret \
  --docker-server=<CNB镜像仓库地址> \
  --docker-username=<部署令牌用户名> \
  --docker-password=<部署令牌密码> \
  -n <命名空间>

字段	说明
`<CNB镜像仓库地址>`	CNB 镜像仓库地址（如 `docker.cnb.cool` 或自定义域名）
`<部署令牌用户名>`	上一步生成的部署令牌用户名
`<部署令牌密码>`	上一步生成的部署令牌密码
`<命名空间>`	工作负载所在的 Namespace

3. 配置工作负载的 imagePullSecrets

在工作负载（Deployment / StatefulSet）的 YAML 中指定 imagePullSecrets：


spec:
  template:
    spec:
      imagePullSecrets:
        - name: cnb-registry-secret # 上一步创建的 Secret 名称
      containers:
        - name: my-app
          image: docker.cnb.cool/your-repo/image:tag

💡 如果集群中有多个命名空间的负载需要拉取 CNB 镜像，需要在每个 Namespace 下分别创建对应的 Secret。

运行结果

权限、参数配置正确后，如果插件更新镜像成功，则插件成功退出，否则失败退出。机制类似 kubectl set image
更新镜像完成后，会监控 10 分钟 pod 滚动状态并打印，方便在流水线日志查看，(设置参数 check_rollout_timeout 为 0 则跳过等待)。
此步骤不会影响插件成功或失败退出结果，最终 pod 滚动结果可在集群中查看详情。
运行机制：类似 kubectl set image, 此插件不会校验待更新镜像是否存在，镜像是否有效、能正常启动。
会直接更新工作负载 yaml 中的 image 字段，并由 K8s 异步调度后续步骤，如 pod 滚动等。

示例

在云原生构建上使用

a.快速用法


# 更新示例镜像配置
main:
  push:
    - stages:
      - name: 使用tke插件更新镜像
        image: tencentcom/deploy-to-tke
        settings:
          secret_id: AKID***MpL4
          secret_key: mRH1***wu0C
          region: ap-***
          cluster_id: cls-***
          namespace: default
          workload_kind: deployment
          workload_name: my-***-deployment
          container_names: container-***-1
          # 可以使用变量形式如 container_images: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT}
          container_images: nginx-***:v1

b.高级用法

如果不希望写密钥明文、可以在密钥（私有）仓库增加一份密钥信息文件 your_secrets.yaml,内容如下：


# your_secrets.yml
secret_id: AKID***MpL4
secret_key: mRH1***wu0C

配置 .cnb.yml,引用上述文件导入环境变量,内容如下：


# 更新示例镜像
main:
  push:
    - stages:
      - name: 使用tke插件更新镜像
        image: tencentcom/deploy-to-tke
        settingsFrom: https://cnb.cool/***/my-secret-repo/-/blob/main/your_secrets.yaml
        settings:
          region: ap-***
          cluster_id: cls-***
          namespace: default
          workload_kind: deployment
          workload_name: my-***-deployment
          container_names: container-***-1
          container_images: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT}
# b.高级用法 完

在 Docker 上使用


docker run --rm  \
    -e PLUGIN_SECRET_ID="***" \
    -e PLUGIN_SECRET_KEY="***" \
    -e PLUGIN_REGION="ap-shanghai" \
    -e PLUGIN_CLUSTER_ID="cls-***" \
    -e PLUGIN_NAMESPACE="development" \
    -e PLUGIN_WORKLOAD_KIND="deployment" \
    -e PLUGIN_WORKLOAD_NAME="my-***-deployment" \
    -e PLUGIN_CONTAINER_NAMES="container-***-1,container-***-2" \
    -e PLUGIN_CONTAINER_IMAGES="nginx-***:v1,nginx-***:v2" \
    tencentcom/deploy-to-tke