Cycloid Toolkit Docker镜像文档

镜像概述和主要用途

Cycloid Toolkit是一个包含工具和脚本的Docker镜像，专为cycloid.io部署流水线设计。其核心用途是提供标准化的工具集，简化部署流程中的关键操作，如Ansible自动化执行、AWS资源清理、Vault认证集成及配置合并等。

核心功能和特性

该镜像集成了以下关键工具，覆盖部署流水线全生命周期需求：

使用场景和适用范围

适用场景

• Ansible自动化部署：通过堡垒机安全执行Ansible Playbook，支持AWS EC2动态inventory
• AWS资源生命周期管理：自动清理过期AMI和ECR镜像，降低存储成本
• Vault安全集成：通过AppRole认证安全获取敏感凭证，避免硬编码密钥
• 配置管理：标准化合并stack模板与环境配置，确保部署一致性

适用范围

• cycloid.io平台部署流水线
• 基于Ansible的自动化运维场景
• 涉及AWS资源管理的CI/CD流程
• 需要Vault密钥管理的安全部署环境

详细的使用方法和配置说明

通用前提

• 镜像拉取：docker pull cycloid/cycloid-toolkit:latest
• 运行环境：Linux平台，需配置正确的环境变量或参数

1. ansible-runner

功能描述

通过堡垒机（或SSH ProxyJump）执行Ansible Playbook，支持AWS EC2动态inventory、Vault加密及角色缓存。

环境变量与参数配置

使用示例（流水线配置）

YAML锚点定义

yaml
shared:
  - &run-ansible-from-bastion
    config:
      platform: linux
      image_resource:
        type: docker-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /usr/bin/ansible-runner
      caches:  # 缓存Ansible角色，加速执行
        - path: ansible-playbook/roles
      inputs:
        - name: ansible-playbook  # 挂载Playbook目录
          path: ansible-playbook

任务引用示例

yaml
- task: run-ansible
  <<: *run-ansible-from-bastion  # 引用YAML锚点
  params:
    BASTION_URL: ((bastion_url))  # 堡垒机地址（从变量注入）
    SSH_PRIVATE_KEY: ((bastion_ssh.ssh_key))  # 堡垒机SSH私钥
    SSH_PRIVATE_KEYS:  # 多私钥配置（可选）
      - ((user1_ssh.ssh_key))
      - ((user2_ssh.ssh_key))
    ANSIBLE_VAULT_PASSWORD: ((ansible_vault_pass))  # Vault解密密码
    AWS_ACCESS_KEY_ID: ((aws_access_key))  # AWS访问密钥（用于动态inventory）
    AWS_SECRET_ACCESS_KEY: ((aws_secret_key))
    EXTRA_ANSIBLE_ARGS: "--limit tag_role_front"  # 限制执行目标
    AWS_DEFAULT_REGION: eu-west-1
    ANSIBLE_PLAYBOOK_NAME: ((customer)).yml  # 动态指定Playbook文件名
    EXTRA_ANSIBLE_VARS:  # 额外Ansible变量
      customer: ((customer))
      project: ((project))
      env: ((env))
    TAGS:  # 仅执行deploy标签任务
      - deploy

2. aws-ami-cleaner

功能描述

清理指定名称模式的旧Amazon AMI，保留最新镜像，适用于频繁构建AMI的自动扩展场景。

环境变量与参数配置

使用示例（流水线配置）

YAML锚点定义

yaml
shared:
  - &aws-ami-cleaner
    task: aws-ami-cleaner
    config:
      platform: linux
      image_resource:
        type: docker-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /usr/bin/aws-ami-cleaner
      params:
        AWS_ACCESS_KEY_ID: ((aws_access_key))
        AWS_SECRET_ACCESS_KEY: ((aws_secret_key))
        AWS_REGION: eu-west-1
        AWS_NAME_PATTERNS: >
                  [
                    "project1_front_prod",
                    "project1_batch_prod"
                  ]  # 清理名称匹配这两个模式的旧AMI

任务引用示例

yaml
- *aws-ami-cleaner  # 直接引用锚点执行清理任务

3. aws-ecr-cleaner

功能描述

清理Amazon ECR仓库中符合条件的旧镜像，支持按标签正则过滤、保留数量配置。

环境变量与参数配置

使用示例（流水线配置）

YAML锚点定义

yaml
shared:
  - &aws-ecr-cleaner
    task: aws-ecr-cleaner
    config:
      platform: linux
      image_resource:
        type: docker-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /usr/bin/aws-ecr-cleaner
      params:
        AWS_ACCESS_KEY_ID: ((aws_access_key))
        AWS_SECRET_ACCESS_KEY: ((aws_secret_key))
        REGION: ((aws_default_region))
        DRYRUN: False  # 生产环境设为False执行实际删除
        IMAGES_TO_KEEP: 2  # 每个仓库保留最新2个镜像
        REPOSITORIES_FILTER: 'foo bar'  # 仅清理名称含foo或bar的仓库
        IGNORE_TAGS_REGEX: 'dev|staging|prod|latest-'  # 保留这些标签的镜像

任务引用示例

yaml
- *aws-ecr-cleaner  # 直接引用锚点执行ECR清理

4. vault-approle-login

功能描述

通过Vault AppRole认证机制获取临时令牌，并将令牌写入文件供后续工具（如Terraform）使用。

环境变量与参数配置

使用示例（流水线配置）

YAML锚点定义

yaml
shared:
  - &vault-approle-login
    task: vault-approle-login
    config:
      platform: linux
      image_resource:
        type: docker-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /usr/bin/vault-approle-login
      outputs:  # 输出令牌文件到vault-token目录
        - name: vault-token
          path: vault-token
    params:
      VAULT_ROLEID: ((vault.role_id))  # AppRole角色ID
      VAULT_SECRETID: ((vault.secret_id))  # AppRole密钥ID
      VAULT_ADDR: ((vault.address))  # Vault服务地址

任务引用示例

yaml
- *vault-approle-login  # 执行认证并输出令牌

5. merge-stack-and-config

功能描述

合并cycloid.io的stack模板（基础设施代码）与用户配置（环境变量、参数等），生成最终部署配置。

环境变量与参数配置

使用示例（流水线配置）

YAML锚点定义

yaml
shared:
  - &merge-stack-and-config
    platform: linux
    image_resource:
      type: docker-image
      source:
        repository: cycloid/cycloid-toolkit
        tag: latest
    run:
      path: /usr/bin/merge-stack-and-config
    outputs:  # 合并结果输出到merged-stack目录
      - name: merged-stack
        path: "merged-stack"

任务引用示例

yaml
- task: merge-stack-and-config
  config:
    <<: *merge-stack-and-config  # 引用锚点
    inputs:  # 挂载stack和config输入目录
      - name: ((project))-config-ansible
        path: "config"  # 用户配置目录
      - name: ((project))-stack-ansible
        path: "stack"   # stack模板目录
      - name: ((project))-terraform-apply  # 可选：挂载Terraform输出作为变量
        path: "terraform"

镜像标签与版本管理

镜像标签基于内置Ansible版本命名，格式为v<ansible-version>（如v2.4）。更新Ansible版本时需同步更新标签：

bash
# 构建新标签镜像
sudo docker build . -t cycloid/cycloid-toolkit:v2.4

# 推送至仓库
sudo docker push cycloid/cycloid-toolkit:v2.4

注意：生产环境建议使用固定标签（如v2.4）而非latest，避免版本变更导致兼容性问题。