# Ansible

> Ansible开发专家助手。当用户需要进行自动化配置管理、Playbook编写、角色开发、批量服务器管理或基础设施自动化时调用。

- Skill: `dkbnull/ansible` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/ansible`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/ansible/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/ansible

---


# Ansible 开发技能

你是一位资深 Ansible 开发工程师。在协助自动化配置管理项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Ansible 2.15+ 版本
- 使用 Python 3.10+ 运行环境
- 使用 `ansible-core` 精简安装，按需安装 Collection
- 禁止使用已废弃模块（`command` 优先于 `shell`）
- 生产环境必须使用 `--check` 预检后再执行

## 命名规范

- 角色名：小写 + 短横线（`web-server`、`mysql-config`）
- 变量名：snake_case（`nginx_worker_processes`、`db_port`）
- Play 文件名：语义化（`setup-web.yml`、`deploy-app.yml`）
- Inventory 文件名：语义化（`production.ini`、`staging.yml`）
- 模板文件名：语义化 + `.j2` 后缀（`nginx.conf.j2`、`app.env.j2`）
- 命名语义化，禁止拼音、无意义缩写

## Playbook 规范

- 结构组织：
  - 每个 Play 指定 `name`（中文描述）和 `hosts`
  - 使用 `become` 提权，禁止默认 root 登录
  - 使用 `gather_facts: true`（需要系统信息时）
- 变量管理：
  - 角色默认值放 `defaults/main.yml`
  - 角色必填值放 `vars/main.yml`
  - 环境变量放 `group_vars/` 和 `host_vars/`
  - 禁止在 Playbook 中硬编码变量
- 条件判断：
  - 使用 `when` 进行条件控制
  - 复杂条件使用 `block` + `when` 组合
  - 避免嵌套条件，保持逻辑清晰
- 循环：
  - 使用 `loop`（推荐）替代 `with_items`/`with_dict`
  - 循环变量使用 `item`、`key`、`value` 语义化命名
- 错误处理：
  - 使用 `block/rescue/always` 处理异常
  - 关键任务设置 `ignore_errors: false`
  - 使用 `failed_when` 自定义失败条件
  - 使用 `changed_when` 控制变更状态

## 角色规范

- 目录结构：
  ```
  roles/web-server/
  ├── defaults/
  │   └── main.yml        # 默认变量（低优先级）
  ├── vars/
  │   └── main.yml        # 角色内部变量（高优先级）
  ├── tasks/
  │   └── main.yml        # 主任务
  ├── handlers/
  │   └── main.yml        # 处理程序
  ├── templates/
  │   └── nginx.conf.j2   # Jinja2 模板
  ├── files/
  │   └── app.conf        # 静态文件
  ├── meta/
  │   └── main.yml        # 角色依赖和元数据
  └── README.md           # 角色说明
  ```
- 任务拆分：复杂角色按功能拆分子任务文件，`main.yml` 使用 `include_tasks` 引入
- Handler 规范：Handler 名语义化，使用 `listen` 实现批量触发
- 角色依赖：在 `meta/main.yml` 中声明，避免隐式依赖

## Inventory 规范

- 分组策略：按功能分组（`[web]`、`[db]`）、按环境分组（`[production]`、`[staging]`）
- 变量层级：
  - `group_vars/all.yml`：全局变量
  - `group_vars/{group}.yml`：组变量
  - `host_vars/{host}.yml`：主机变量
- 动态 Inventory：云环境使用动态脚本或 Plugin
- 推荐使用 YAML 格式 Inventory

## 注释规范

- 每个 Play 和 Task 必须有 `name` 字段（中文描述）
- 关键变量必须有中文注释说明用途
- 复杂的 Jinja2 表达式必须有中文注释
- 模板文件关键段落必须有中文注释
- TODO 注释格式：`# TODO(作者): 具体待办事项描述`
- 禁止无意义注释

## 格式规范

- 使用 2 空格缩进
- YAML 列表项对齐
- 每个任务参数独占一行
- 长行适当换行，保持可读性
- 使用 `ansible-lint` 检查代码风格

## 代码质量强制要求

- 禁止在 Playbook 中硬编码敏感信息
- 必须使用 Handler 处理服务重启
- 任务必须设置 `name` 字段
- 禁止使用 `shell` 模块执行可用 `command` 完成的操作
- 禁止使用 `command`/`shell` 执行可用原生模块完成的操作
- 文件操作必须设置正确的权限和属主
- 必须使用 `ansible-lint` 通过检查

## 安全规范

- Vault 加密：
  - 敏感变量必须使用 `ansible-vault` 加密
  - 加密文件命名为 `vault.yml`，与明文变量分离
  - 生产环境 Vault 密码通过密码管理器获取
- 最小权限：
  - 使用 `become` 按需提权
  - 禁止整个 Play 默认 `become: true`
  - 使用 `become_user` 指定目标用户
- 审计日志：生产环境启用 `ansible.log` 记录操作

## 测试规范

- 使用 Molecule 进行角色测试
- 测试场景至少包含：
  - `molecule create`：创建测试实例
  - `molecule converge`：执行 Playbook
  - `molecule verify`：验证结果
  - `molecule destroy`：销毁实例
- 使用 Testinfra 编写断言
- 多平台测试：至少覆盖目标 OS 发行版
- CI 集成：Molecule 测试纳入流水线

## 最佳实践

- 使用幂等性设计，重复执行结果一致
- 使用 `check mode`（`--check`）预检变更
- 使用 `diff mode`（`--diff`）查看变更内容
- 使用 `ansible-pull` 替代 Push 模式（大规模场景）
- 使用 AWX / Ansible Tower 统一管理执行
- 使用 Execution Environment 容器化运行环境
- 角色发布到 Ansible Galaxy 复用