cimg/azure Docker镜像文档

镜像概述和主要用途

cimg/azure 是由CircleCI开发的Docker镜像，专为持续交付（Continuous Delivery）和部署（Deployment）流水线设计。该镜像基于 cimg/deploy 构建，预装了Azure CLI及相关工具，适用于在CircleCI环境中执行与Azure云服务相关的自动化部署任务。每个镜像标签对应一个日期快照，确保构建环境的可确定性。

核心功能和特性

核心功能

• 预装Azure工具链：包含Azure CLI及相关部署工具，可直接用于与Azure云服务交互。
• 基于cimg/deploy：继承父镜像的部署能力，同时默认集成Node.js环境（基于cimg/deploy的Node.js变体）。
• 定期更新：每月发布新版本，同步更新核心工具至最新稳定版，确保兼容性。

关键特性

• 无独立Node.js变体：无需额外指定Node.js版本，基础镜像已预装Node.js。
• 确定性标签：采用日期快照标签，避免因工具版本变更导致的构建中断。
• 子模块管理：通过独立的构建脚本子模块（cimg-shared）维护构建逻辑，确保跨镜像一致性。

使用场景和适用范围

适用场景

• CircleCI Azure部署流水线：在CircleCI作业中使用docker执行器，通过Azure CLI完成资源部署、配置更新等任务。
• 多环境部署验证：利用预装工具链在CI/CD流程中自动化测试、打包及部署Azure资源。
• 持续交付流程标准化：通过固定标签确保团队内所有成员使用一致的部署工具版本。

适用范围

• 需在CircleCI中集成Azure云服务的开发团队。
• 依赖Azure CLI、Node.js及相关工具的自动化部署流程。
• 对构建环境可重复性和版本确定性有较高要求的CI/CD场景。

详细使用方法和配置说明

基本使用（CircleCI配置）

在CircleCI的.circleci/config.yml中，通过docker执行器指定cimg/azure镜像：

jobs:
  azure-deploy:
    docker:
      - image: cimg/azure:2022.08.1  # 使用2022年8月第1次发布的镜像
    steps:
      - checkout
      - run: 
          name: 登录Azure并部署资源
          command: |
            az login --service-principal -u $AZURE_CLIENT_ID -p $AZURE_CLIENT_SECRET --tenant $AZURE_TENANT_ID
            az group deployment create --resource-group my-rg --template-file azure-deploy.json

标签方案说明

镜像标签格式为 YYYY.MM.I，其中：

• YYYY：4位年份（如2023）
• MM：2位月份（如09）
• I：当月发布序号（从1开始，用于补丁版本）

示例：cimg/azure:2023.09.1 表示2023年9月第1次发布的镜像；若当月需修复漏洞，将发布2023.09.2。

本地开发与构建

环境要求

• Linux（Ubuntu测试通过）或macOS系统
• Bash 4+
• Docker Engine 20.10+

克隆仓库

社区用户（无仓库写入权限）：

# 克隆时递归拉取子模块
git clone --recurse-submodules [***]
cd cimg-azure

# 若已克隆，手动初始化子模块
git submodule update --init

维护者（有仓库写入权限）：

git clone --recurse-submodules ***:CircleCI-Public/cimg-azure.git

生成Dockerfile

使用子模块中的脚本生成指定版本的Dockerfile：

# 生成标签为2023.10.1的Dockerfile
./shared/gen-dockerfiles.sh 2023.10.1
# 生成的文件位于 ./2023.10/Dockerfile

本地构建与测试

# 进入生成目录
cd 2023.10
# 构建镜像
docker build -t test/azure:2023.10.1 .
# 启动交互式测试
docker run -it test/azure:2023.10.1 bash

维护者发布流程

1. 生成发布分支：

   # 发布2023.10.2版本（假设为10月第2次发布）
   ./shared/release.sh 2023.10.2
   

   脚本会自动创建分支、生成Dockerfile、提交变更并推送至GitHub。

2. 触发镜像构建：

   • 提交信息需包含[release]标记，CircleCI流水线会识别并触发镜像构建。
   • 构建通过后，合并PR至主分支，自动推送镜像至Docker Hub。

3. 子模块更新： 若需同步构建脚本变更（来自cimg-shared）：

   cd shared
   git pull origin main  # 拉取最新构建脚本
   cd ..
   git add shared
   git commit -m "更新子模块以支持XX功能"
   

配置参数与环境变量

核心预装工具

• Azure CLI：默认路径/usr/local/bin/az，支持所有标准Azure命令。
• Node.js：版本与cimg/deploy父镜像同步，可通过node -v验证。
• 相关依赖：curl、jq、git等基础工具已预装，满足常见部署脚本需求。

标签参数说明

贡献指南

• Issue提交：仅接受工具版本更新、功能缺失或bug报告，使用问题模板描述详细场景。
• PR规范：
  • 父镜像变更需通过发布新版本而非修改现有镜像实现。
  • 工具版本更新需附官方release说明，确保兼容性。
• 讨论渠道：技术支持请访问 CircleCI Discuss。

额外资源

• CircleCI官方文档
• CircleCI配置参考
• Docker官方文档
• cimg-shared构建脚本仓库

许可证

本镜像及相关代码以MIT许可证开源，详情见 LICENSE。