Bring/Tools/CVMTools

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

Branch

Tag

没猫饼

refactor(trigger): 移除预检模式开关配置

2eef4954

23 commits

.cnb
src
.cnb.yml
.gitignore
Dockerfile
README.md
requirements.txt

CVMTools

基于 CNB 云原生构建平台的腾讯云 CVM 管理插件。通过页面按钮一键创建/管理云服务器，支持定时自动销毁。

功能

动作	说明
创建 CVM	自动匹配机型和可用区，支持竞价实例，定时自动销毁，支持开机初始化脚本
列出实例	按标签/状态过滤，导出变量供后续流水线使用
销毁实例	按实例ID销毁，支持预检模式
清理过期实例	按保留分组扫描过期实例并销毁

作为插件使用

前置条件

一个 CNB 密钥仓库，包含腾讯云 API 密钥文件：

# 密钥仓库中的文件，如 ThirdParty/TencentCloud.yml
SECRET_ID: "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
SECRET_KEY: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

插件镜像地址：docker.cnb.cool/bring/tools/cvmtools:latest

方式一：在流水线中直接调用

在你的项目 .cnb.yml 中引用本插件镜像：

# 定义密钥仓库引用
.cvm_imports: &cvm_imports
  - https://cnb.cool/your-org/your-keystore/-/blob/main/TencentCloud.yml

"**":
  # 创建实例
  web_trigger_create_cvm:
    - imports: *cvm_imports
      stages:
        - name: 创建 CVM 实例
          image: docker.cnb.cool/bring/tools/cvmtools:latest
          settings:
            action: create
            secret_id: $SECRET_ID
            secret_key: $SECRET_KEY
            region: ap-guangzhou
            instance_type: SA9.MEDIUM4
            image: Ubuntu 22.04
            retain: 3h
            init_script: |
              #!/bin/bash
              apt-get update && apt-get install -y docker.io
          exports:
            instance_ids: INSTANCE_IDS
            public_ips: PUBLIC_IPS
        - name: 使用创建结果
          script:
            - echo "实例ID: $INSTANCE_IDS"
            - echo "公网IP: $PUBLIC_IPS"
            - ssh root@$PUBLIC_IPS "echo connected"

  # 列出实例
  web_trigger_list_cvm:
    - imports: *cvm_imports
      stages:
        - name: 列出实例
          image: docker.cnb.cool/bring/tools/cvmtools:latest
          settings:
            action: list
            secret_id: $SECRET_ID
            secret_key: $SECRET_KEY
            region: ap-guangzhou
            tag_key: cvmtools:managed
            tag_value: "true"
          exports:
            instance_ids: INSTANCE_IDS
            public_ips: PUBLIC_IPS

  # 销毁实例
  web_trigger_terminate_cvm:
    - imports: *cvm_imports
      stages:
        - name: 销毁实例
          image: docker.cnb.cool/bring/tools/cvmtools:latest
          settings:
            action: terminate
            secret_id: $SECRET_ID
            secret_key: $SECRET_KEY
            region: ap-guangzhou
            instance_ids: $instance_ids
            dry_run: "false"

  # 清理过期实例
  web_trigger_cleanup:
    - imports: *cvm_imports
      stages:
        - name: 清理过期实例
          image: docker.cnb.cool/bring/tools/cvmtools:latest
          settings:
            action: terminate-by-tag
            secret_id: $SECRET_ID
            secret_key: $SECRET_KEY
            region: ap-guangzhou
            tag_key: cvmtools:managed
            tag_value: "true"
            retain_group: short
            dry_run: "false"

方式二：配合 web_trigger 按钮使用

在 .cnb/web_trigger.yml 中配置自定义按钮，点击按钮时弹出表单填写参数：

branch:
  - buttons:
      - name: 创建 CVM
        event: web_trigger_create_cvm
        inputs:
          region:
            name: 地域
            type: select
            default: ap-guangzhou
            options:
              - name: 广州
                value: ap-guangzhou
              - name: 上海
                value: ap-shanghai
          instance_type:
            name: 机型
            type: select
            default: SA9.MEDIUM4
            options:
              - name: "SA9.MEDIUM4 (2C4G)"
                value: SA9.MEDIUM4
              - name: "SA9.LARGE8 (4C8G)"
                value: SA9.LARGE8
          retain:
            name: 保留时长
            type: select
            default: 3h
            options:
              - name: 1 小时
                value: 1h
              - name: 3 小时
                value: 3h
              - name: 1 天
                value: 1d

完整的按钮配置参见本仓库 .cnb/web_trigger.yml

插件参数

公共参数

参数	必选	默认值	说明
`action`	是	-	`create` / `list` / `terminate` / `terminate-by-tag`
`secret_id`	是	-	腾讯云 SecretId
`secret_key`	是	-	腾讯云 SecretKey
`region`	否	`ap-guangzhou`	地域
`dry_run`	否	`false`	预检模式（写操作时仅展示不执行）

create 参数

参数	默认值	说明
`instance_type`	-	机型（如 `SA9.MEDIUM4`），与 cpu/memory 二选一
`cpu`	`2`	CPU 核数（未指定 instance_type 时生效）
`memory`	`4`	内存 GB（未指定 instance_type 时生效）
`image`	`Ubuntu 22.04`	镜像ID（`img-xxx`）或关键字
`disk_size`	`50`	系统盘大小 GB
`disk_type`	`CLOUD_BSSD`	`CLOUD_BSSD`(通用SSD) / `CLOUD_HSSD`(增强SSD)
`bandwidth`	`5`	公网带宽 Mbps
`name`	`cvm-{timestamp}`	实例名称
`retain`	`3h`	保留时长：`1h`/`3h`/`6h`/`12h`/`1d`/`3d`/`7d`/`never`
`charge_type`	`POSTPAID_BY_HOUR`	`POSTPAID_BY_HOUR`(按量) / `SPOTPAID`(竞价)
`spot_max_price`	-	竞价上限（元/小时），仅竞价模式生效
`password`	-	登录密码
`key_id`	-	SSH 密钥ID（优先于密码）
`sg_id`	-	安全组ID（留空自动创建全放通安全组）
`count`	`1`	创建数量
`init_script`	-	开机初始化脚本（Shell），实例就绪后通过 TAT 执行

list 参数

参数	默认值	说明
`tag_key`	-	按标签键过滤
`tag_value`	-	按标签值过滤
`instance_ids`	-	实例ID列表（逗号分隔）
`state`	-	按状态过滤（`RUNNING`/`STOPPED` 等）

terminate 参数

参数	说明
`instance_ids`	要销毁的实例ID（逗号分隔），必填

terminate-by-tag 参数

参数	默认值	说明
`tag_key`	`cvmtools:managed`	标签键
`tag_value`	`true`	标签值
`retain_group`	-	按分组过滤：`short` / `long` / `permanent`
`only_expired`	`true`	仅销毁已过期实例

导出变量

插件通过 ##[set-output key=value] 输出变量，配合 exports 映射为环境变量：

变量	动作	说明
`instance_ids`	create / list	实例ID（逗号分隔）
`public_ips`	create / list	公网IP（逗号分隔）
`private_ips`	create / list	内网IP（逗号分隔）
`expire_at`	create	过期时间 UTC
`instance_type`	create	实际使用的机型
`instance_count`	create / list	实例数量
`init_invocation_id`	create	TAT 初始化脚本执行活动ID
`init_script_status`	create	初始化脚本执行结果（逗号分隔）
`instances_json`	list	实例详情 JSON（base64 编码）
`terminated_ids`	terminate / terminate-by-tag	已销毁的实例ID
`terminated_count`	terminate / terminate-by-tag	已销毁数量

使用示例：

stages:
  - name: 创建实例
    image: docker.cnb.cool/bring/tools/cvmtools:latest
    settings:
      action: create
      # ...
    exports:
      instance_ids: INSTANCE_IDS
      public_ips: PUBLIC_IPS
  - name: 部署应用
    script: ssh root@$PUBLIC_IPS "docker pull myapp && docker run -d myapp"

创建流程与 API 调用

创建实例时按顺序执行以下步骤（有初始化脚本时为 8 步，无则 6 步）：

步骤	说明	调用 API
[1] 解析机型和可用区	匹配机型，查询可用区库存	`cvm:DescribeInstanceTypeConfigs` + `cvm:DescribeZoneInstanceConfigInfos`
[2] 解析镜像	按关键字或 ID 查找镜像	`cvm:DescribeImages`
[3] 解析安全组	查找或自动创建全放通安全组	`vpc:DescribeSecurityGroups` + `vpc:CreateSecurityGroupWithPolicies`（按需）
[4] 构建请求参数	本地计算，无网络调用	—
[5] 创建实例	发起创建请求	`cvm:RunInstances`
[6] 等待实例就绪	轮询直到所有实例 RUNNING	`cvm:DescribeInstancesStatus`（轮询）
[7] 等待 TAT Agent 上线	轮询直到 Agent 状态 Online	`tat:DescribeAutomationAgentStatus`（轮询）
[8] 执行初始化脚本	下发脚本并等待执行完成	`tat:RunCommand` + `tat:DescribeInvocationTasks`（轮询）

最后调用 cvm:DescribeInstances 获取实例详情（IP 等）用于结果输出。

步骤 [7] 和 [8] 仅在设置了 init_script 时执行。

生命周期管理

保留时长	分组	用途
1h / 3h / 6h	`short`	临时调试
12h / 1d / 3d / 7d	`long`	开发测试
never	`permanent`	长期运行

实例创建时会打上标签：

cvmtools:managed=true — 标识由本插件创建
cvmtools:retain=3h — 保留时长
cvmtools:retain-group=short — 保留分组
cvmtools:expire-at=2026-05-02T18:00:00Z — 过期时间

到期后通过腾讯云 ActionTimer 自动销毁。也可通过「清理过期实例」按钮按分组扫描兜底。

默认行为

VPC: 使用地域默认 VPC/子网
安全组: 未指定时自动查找/创建 cvmtools-allow-all（入出全放通）
机型匹配优先级: SA9 > SA5 > S5 > SA3 > S6
可用区: 自动选择首个有该机型库存的可用区
写操作安全: 销毁类按钮默认开启预检模式，需手动关闭才执行

本地开发

pip install -r requirements.txt

# 预检模式测试创建
export PLUGIN_ACTION=create
export PLUGIN_SECRET_ID=AKIDxxx
export PLUGIN_SECRET_KEY=xxx
export PLUGIN_REGION=ap-guangzhou
export PLUGIN_INSTANCE_TYPE=SA9.MEDIUM4
export PLUGIN_IMAGE="Ubuntu 22.04"
export PLUGIN_RETAIN=1h
export PLUGIN_DRY_RUN=true
python -m src.main

# Docker 构建测试
docker build -t cvmtools .
docker run --rm -e PLUGIN_ACTION=list -e PLUGIN_SECRET_ID=xxx -e PLUGIN_SECRET_KEY=xxx cvmtools