矩尺全栈智能流量管理平台

主题切换

配置集合管理：Jenkins 脚本自动化管理 ​

本示例用于在 Jenkins 中将一个目录内的配置文件上传到同一个配置集合，并在全部文件上传成功后执行一次同步。

准备文件 ​

下载以下示例文件，并将脚本和依赖文件放入客户自己的代码仓库：

建议采用下面的目录结构：

text
project/
├── ci/
│   ├── config_set_sync.py
│   └── requirements.txt
└── config-sets/
    └── production/
        ├── address.yaml
        ├── pool.jsonc
        └── virtual-service.yaml

脚本只读取指定目录的第一层文件，支持 .json、.jsonc、.yaml 和 .yml。隐藏文件、其他扩展名和子目录会被忽略；目录中没有支持的配置文件时，脚本返回失败。

addr.yaml 是最小格式示例。执行后会在目标系统中创建名为 jenkins-config-set-example-addresses 的地址资源，请只在测试环境使用，或先根据实际环境修改名称和内容。

生成 Token ​

  1. 登录 Web 控制台并切换到 Jenkins 需要操作的目标租户。
  2. 点击右上角用户头像，在下拉菜单中点击“生成 Token”。
  3. 设置过期时间。自动化任务建议设置为 1 年，并在到期前安排轮换。
  4. 生成并复制 Token，将其保存为 Jenkins 的 Secret text 类型凭据，例如凭据 ID normae-config-set-token。

Token 绑定生成时的用户、租户和角色。该角色需要配置集合的读写权限。脚本通过 X-NORMAE-AUTH-TOKEN 请求头使用 Token，不要将 Token 写入 Python 文件、Jenkinsfile 或代码仓库。

同一用户、租户和角色重新生成 Token 后，原有 Token 会立即失效。轮换时应立即更新 Jenkins 凭据，并运行一次任务验证。

安装依赖 ​

Jenkins Agent 需要 Python 3.8 或更高版本。安装脚本唯一的第三方依赖：

bash
python3 -m pip install -r ci/requirements.txt

脚本默认校验 HTTPS 证书。如果管理节点使用私有 CA，请在 Jenkins 中安全保存 CA 文件，并设置标准环境变量：

bash
export REQUESTS_CA_BUNDLE=/path/to/private-ca.pem

不要通过关闭证书校验解决私有 CA 问题。

命令行调用 ​

脚本从环境变量读取管理节点地址和 Token：

bash
export NORMAE_BASE_URL='https://<管理节点地址>'
export NORMAE_TOKEN='<由 Jenkins 凭据注入的 Token>'

python3 ci/config_set_sync.py config-sets/production

默认使用目录名 production 作为配置集合名称。需要使用其他名称时指定 --name：

bash
python3 ci/config_set_sync.py config-sets/production --name production-app-1

脚本执行以下步骤：

  1. 按名称精确查询配置集合；存在则复用，不存在则创建。
  2. 按文件名顺序逐个上传目录中的全部配置文件。
  3. 全部文件上传成功后执行一次配置集合同步。
  4. 查询同步状态；只有状态和状态消息都表示同步成功时，进程才返回退出码 0。

配置集合会自行识别文件内容是否变化，因此脚本每次都上传全部文件，不在本地重复比较文件内容。

Jenkins Pipeline 示例 ​

以下 Declarative Pipeline 假设脚本位于 ci/，配置集合目录位于 config-sets/production/，并且 Jenkins Agent 已安装依赖：

groovy
pipeline {
    agent any

    environment {
        NORMAE_BASE_URL = 'https://<管理节点地址>'
        NORMAE_TOKEN = credentials('normae-config-set-token')
    }

    stages {
        stage('同步配置集合') {
            steps {
                sh '''
                    python3 ci/config_set_sync.py \
                        config-sets/production \
                        --name production-app-1
                '''
            }
        }
    }
}

Jenkins 会根据脚本退出码判断阶段结果。同步失败、认证失败、目录为空或任一文件上传失败时，脚本返回非零退出码。

增量上传说明 ​

本脚本采用增量上传方式：上传会新增文件或覆盖远端同名文件，但本地目录中缺少某个文件时，不会自动删除配置集合中的远端文件。

需要删除远端文件及其创建的资源时，请在 Web 控制台的配置集合详情中删除该文件，再执行同步。删除文件会删除此前由该文件创建的资源，操作前应确认影响范围。

如果某个文件上传失败，脚本不会执行同步，但此前已上传的文件可能仍处于“待同步”状态。修复问题后可以直接重新运行整个 Jenkins 任务；配置集合会重新接收全部文件并统一同步。

输出示例 ​

text
复用配置集合: production-app-1 (ID 12)
上传: address.yaml
上传: pool.jsonc
上传: virtual-service.yaml
同步成功 (耗时2.3秒)

脚本不会在输出中打印 Token。若任务失败，请先查看错误信息和配置集合的同步状态，再检查文件格式、资源依赖、Token 所属租户及角色权限。

相关文档 ​