woodpeckerci/plugin-ansible

Woodpecker CI Ansible插件镜像文档

概述

本镜像为Woodpecker CI（持续集成/持续部署工具）的官方Ansible插件，旨在将Ansible集成到CI/CD流程中，实现通过Ansible playbook自动化执行配置管理、应用部署、环境初始化等运维任务，提升CI/CD流程的自动化程度和运维效率。

核心功能与特性

• Woodpecker CI原生集成：无缝对接Woodpecker CI流水线，无需额外适配即可在CI/CD任务中调用。
• Ansible功能支持：完整支持Ansible核心功能，包括playbook执行、inventory管理、变量注入、Vault加密解密等。
• 灵活配置：通过环境变量或Woodpecker CI配置参数自定义Ansible执行行为，适配不同场景需求。
• 轻量级设计：基于官方Ansible镜像优化，减少镜像体积，降低CI/CD流程资源消耗。
• 敏感信息保护：支持通过Woodpecker CI Secrets管理敏感数据（如Ansible Vault密码），避免明文暴露。

使用场景

• 自动化服务器配置：在CI/CD流程中通过Ansible playbook初始化服务器环境（如安装依赖、配置服务）。
• 应用部署：从代码构建到应用部署全流程自动化，通过Ansible实现应用在目标服务器的部署与启停。
• 多环境差异化部署：针对开发、测试、生产等不同环境，通过动态变量切换Ansible配置，实现差异化部署。
• 配置文件管理：利用Ansible模板功能生成环境特定配置文件，并自动同步到目标服务器。

使用方法与配置说明

前置条件

• 已部署Woodpecker CI服务，并配置好CI/CD项目。
• 目标服务器已开启SSH访问权限（Ansible通过SSH连接目标节点）。
• 若使用Ansible Vault加密文件，需提前准备Vault密码。

核心配置参数

通过Woodpecker CI流水线配置文件（.woodpecker.yml）的settings字段传递参数，支持以下核心配置：

部署示例

1. 基础用法（执行简单playbook）

在Woodpecker CI项目的.woodpecker.yml中添加以下配置，实现通过Ansible部署应用：

yaml
pipeline:
  deploy-to-prod:
    image: woodpeckerci/plugin-ansible
    settings:
      playbook: deploy/prod.yml  # 项目中的Ansible playbook路径
      inventory: inventory/prod.ini  # 目标主机inventory文件
      verbose: true  # 启用详细输出
    when:
      branch: main  # 仅在main分支触发

2. 带变量注入与Vault解密

若需传递动态变量并解密Vault加密文件，配置示例如下：

yaml
pipeline:
  deploy-with-vars:
    image: woodpeckerci/plugin-ansible
    settings:
      playbook: deploy/staging.yml
      inventory: inventory/staging.ini
      extra_vars: '{"app_version": "${CI_COMMIT_SHA:0:8}", "env": "staging"}'  # 注入CI提交哈希作为版本号
      vault_password:
        from_secret: ansible_vault_pwd  # 从Woodpecker Secrets获取Vault密码
    when:
      branch: develop

3. 自定义工作目录

若Ansible相关文件（playbook、inventory等）存放在项目子目录（如ansible/），需指定工作目录：

yaml
pipeline:
  ansible-task:
    image: woodpeckerci/plugin-ansible
    settings:
      playbook: prod.yml  # 相对于工作目录的路径（ansible/prod.yml）
      inventory: inventory.ini  # 相对于工作目录的路径（ansible/inventory.ini）
      directory: ansible/  # 工作目录设为项目下的ansible文件夹

注意事项

• SSH密钥配置：若目标主机通过SSH密钥认证，需将SSH私钥通过Woodpecker Secrets挂载到插件容器（通常通过ssh_key参数或挂载~/.ssh/id_rsa实现，具体需参考镜像版本说明）。
• 网络访问：确保Woodpecker CI Runner可访问目标主机（Ansible需通过网络连接目标节点）。
• 版本兼容性：建议使用与Woodpecker CI版本匹配的插件镜像（如Woodpecker v1.x对应plugin-ansible v1.x系列）。

参考链接

• Woodpecker CI官方文档
• Ansible官方文档
• https://github.com/woodpecker-ci/plugin-ansible