ansible

Ansible：生产级配置管理

编写、审查和设计 Ansible 自动化，从单个 Playbook 到多层、符合合规要求的基础设施管理。目标是实现幂等、可审计、可维护的自动化，并确保其在本地和 CI/CD 中的运行方式一致。

目标版本（2026 年 10 月）：

• ansible-core 2.21.4（当前稳定版，控制节点需使用 Python 3.12+）；固定版本前，请在支持矩阵中核实受管节点的 Python 支持情况和分支 EOL
• ansible（community package）14.4.0（依赖 ansible-core 2.21）
• molecule 26.9.0、ansible-lint 26.9.0、ansible-navigator 26.9.0（CalVer）
• ansible-builder 3.1.1（EE 定义 v3）
• AWX 24.6.1（最后一次正式发布于 2024 年 7 月；上游 AWX 因重大重构暂停发布，devel 分支仍活跃——请关注 ansible/awx；awx-operator ~2.19.x 仍用于 K8s 部署）。在推荐具体版本或安装方式前，请核实当前 AWX/AAP 发布状态。
• AAP 2.7（当前版本系列）；部署前，请在厂商生命周期文档中核实受支持的安装方式和补丁版本

本技能根据上下文涵盖四个领域：

• Playbook - 任务、处理程序、变量、条件、循环、块、模板、Jinja2
• 角色与集合 - 角色结构、集合打包、Galaxy/Automation Hub、Molecule 测试
• 运维 - 清单、执行环境、CI/CD 集成、Vault、ansible-navigator
• 合规 - PCI-DSS 4.0 加固、CIS 基准、Ansible-Lockdown、审计日志

适用场景

• 编写或审查 Ansible Playbook、角色或集合
• 在 Terraform 完成基础设施配置后配置服务器（日常运维）
• 操作系统加固（CIS 基准、STIG、PCI-DSS 配置要求）
• 管理软件包、服务、用户、防火墙规则、cron 作业和配置文件
• 使用 Molecule 或 tox-ansible 测试自动化
• 设置 Ansible Vault 以管理密钥
• 设计清单结构（静态、动态、多环境）
• 构建执行环境，确保运行环境一致
• 将 Ansible 集成到 CI/CD 流水线（GitLab CI、GitHub Actions）
• 审查 AI 生成的 Playbook，检查其正确性和惯用模式

不适用场景

• 基础设施配置（VPC、RDS、EC2、云资源）——使用 terraform
• Kubernetes 清单、Helm Chart、集群架构——使用 kubernetes
• Dockerfile、Compose 堆栈、容器镜像优化——使用 docker
• CI/CD 流水线设计（阶段、Runner、缓存）——使用 ci-cd
• 应用代码安全审计（SAST、依赖扫描）——使用 security-audit
• Shell 脚本或一次性命令——使用 shell-scripting
• 防火墙设备管理（OPNsense/pfSense）——使用 opnsense-pfsense
• 单机操作系统级管理问题（软件包安装、用户管理、不涉及自动化的服务配置）——使用对应的发行版技能：debian-ubuntu、rhel-fedora、kali-linux 或 arch-linux

---

AI 自检

AI 工具总是会犯同样的 Ansible 错误。在返回任何生成的 playbook、role 或 task 之前，请对照此列表进行检查：

• 全程使用 FQCN（ansible.builtin.copy，而非 copy）。AI 几乎不会在没有提示的情况下做到这一点。
• 需要提升权限时，设置 become: true（AI 经常会忘记）
• 每个处理机密、密码、令牌或 API 密钥的任务都设置 no_log: true（CVE-2024-8775 证明了这一点的重要性）
• 每个任务都有描述性 name: 字段（AI 有时会在简单任务中省略名称）
• Handler 名称唯一，且 notify: 字符串完全匹配（拼写错误会导致静默失败）
• 变量使用带引号的 {{ var }}："{{ my_var }}"，而非 {{ my_var }}（不带引号的 Jinja2 会导致 YAML 解析失败）
• 如果有 Ansible 模块可用于该操作，就不要使用 command/shell/raw
• 任务具有幂等性——运行两次会产生相同结果（注意没有 creates/removes 的 command/shell 任务）
• 不要硬编码值——IP、路径、软件包版本、用户名都应放入带默认值的变量中
• ansible.builtin.apt/ansible.builtin.dnf 使用 state: present，而非 state: latest（除非明确要求升级）
• 循环变量使用 item（默认值），或在嵌套循环中通过 loop_var 重命名（AI 容易混淆循环变量）
• 使用 block/rescue/always 处理错误，而非单独使用 ignore_errors: true
• 不要使用 src: 指向非 .j2 文件的 ansible.builtin.template（即使可以正常运行，也容易造成混淆）
• 在 command/shell 任务上设置 changed_when/failed_when，以避免错误报告变更
• 为逻辑任务组添加标签，以便选择性执行
• 检查 Collection 文档：模块参数和返回值应与已安装的 Collection 版本一致
• 验证幂等性：在可行的情况下，通过检查模式或第二次运行验证 changed/ok 行为
• 应用跨领域的 Agent 卫生规范——参见 references/agent-hygiene.md

---

性能

• 对大型主机群使用有针对性的清单、标签和 --limit；迭代单个 role 时，避免对整个主机群运行。
• 仅收集所需事实，并在支持的情况下缓存事实，以适应速度较慢或延迟较高的环境。
• 优先使用原生模块，而非 shell 循环，以便 Ansible 能够批量处理、安全地显示差异并报告幂等性。

---

最佳实践

• 在生产自动化中，将 Collection 版本固定在 requirements.yml 中。
• 首先使用 --check --diff 运行有破坏性的 playbook，并要求对生产主机使用经人工审核的 limit。
• 不要让 Vault 值出现在差异、日志、callback 输出和生成的示例中。

工作流

复制此检查清单并跟踪进度：

• 步骤 1：确定领域
• 步骤 2：收集需求（目标 OS、权限、连接、机密、清单）
• 步骤 3：构建 playbook、role 或配置
• 步骤 4：语法检查、lint 和 --check --diff 均通过（任何一项失败时，修复问题并返回步骤 3）
• 通过生产检查清单和 AI 自检

步骤 1：确定领域

根据请求判断：

• “编写一个 playbook 来配置 X” -> Playbooks
• “为 X 创建一个可复用的 role” -> Roles & Collections
• “设置清单”/“CI/CD”/“vault”/“EE” -> Operations
• “强化此服务器”/“CIS 基准”/“PCI 合规性” -> Compliance
• “审查此 playbook/role” -> 应用生产检查清单 + 关键规则 + AI 自检

大多数实际任务都涉及多个领域。从 playbook 开始，在明确需要复用时提取为 role，最后再接入运维流程。

步骤 2：收集需求

编写 YAML 前，先确定：

• 目标操作系统：RHEL/CentOS、Ubuntu/Debian、Alpine、Windows —— 会影响模块选择
• 目标主机上的 Python 版本：根据 Target versions 下方链接的支持矩阵，检查受管节点对固定版本 ansible-core 的支持情况
• 权限提升：become 方法（sudo、su、doas、Windows 的 runas）
• 连接方式：SSH（默认）、WinRM（Windows）、local、network_cli（网络设备）
• 幂等性：每个任务都必须可安全地多次运行
• 密钥：Ansible Vault、HashiCorp Vault、CI/CD 密钥、环境变量
• 测试：Molecule 场景？tox-ansible 矩阵？集成测试？
• 合规性：是否涉及 PCI-DSS？CIS 基准等级？STIG 配置文件？
• 清单：静态、动态（云端）还是混合？是否有多个环境？
• 执行方式：ansible-playbook（直接执行）、ansible-navigator（EE）、AWX/AAP（平台）？

步骤 3：构建

遵循下方的领域专属章节。完成前，务必执行步骤 4、references/production-checklist.md 中的生产环境检查清单，以及 AI 自检。

步骤 4：验证

依次运行语法检查、lint 和 --check --diff。如有任何失败，修复报告的问题，返回步骤 3，然后从语法检查开始重新运行；只有三项检查全部通过后才能完成。

# Syntax check (fast, no connection needed)
ansible-playbook playbook.yml --syntax-check

# Lint (use production profile for strictest checks)
if command -v ansible-lint >/dev/null; then
  ansible-lint --profile production playbook.yml
else
  echo "ansible-lint not installed: lint NOT run; report it as unverified"
fi

# Dry run (needs inventory + connectivity)
ansible-playbook playbook.yml --check --diff

仅适用于角色：如果存在场景，则添加 Molecule：

if command -v molecule >/dev/null; then
  molecule test                        # full cycle: create, converge, verify, destroy
  # molecule converge                  # just apply (dev loop)
  # molecule verify                    # run verification only
else
  echo "molecule not installed: role tests NOT run; report them as unverified"
fi

任何非检查模式的运行都会应用更改。仅使用 --limit 运行，并在将目标设为生产主机前获得人工批准：

# Navigator (EE-based execution)
ansible-navigator run playbook.yml --mode stdout --eei <ee-image> --limit <hosts>

---

Playbook

阅读 references/playbook-patterns.md，了解完整且可直接复制粘贴的任务示例（服务、软件包、文件、模板、用户、防火墙、cron、systemd、OpenRC）和 Jinja2 模式。

结构

---
- name: Configure web servers
  hosts: webservers
  become: true
  gather_facts: true

  vars:
    app_port: 8080
    app_user: appuser

  pre_tasks:
    - name: Update apt cache
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600
      when: ansible_os_family == "Debian"

  roles:
    - role: common
      tags: [common]
    - role: nginx
      tags: [nginx]

  tasks:
    - name: Ensure application directory exists
      ansible.builtin.file:
        path: /opt/app
        state: directory
        owner: "{{ app_user }}"
        mode: "0755"

  handlers:
    - name: Restart nginx
      ansible.builtin.systemd:
        name: nginx
        state: restarted
        daemon_reload: true

关键模式

变量优先级（共 22 个级别；最重要的级别按优先级从低到高排列）：

1. 角色默认值（defaults/main.yml）——优先级最低，旨在被覆盖
2. Inventory 变量（group_vars/、host_vars/）
3. Play 变量
4. Task 变量
5. Extra 变量（-e）——优先级最高，会覆盖所有内容

经验法则：将默认值放在角色的 defaults/ 中，将特定于环境的值放在 group_vars/ 中，将一次性覆盖项放在 host_vars/ 中，并通过 -e 进行紧急覆盖。

Handlers：仅在被发生更改的 task 通知后才会运行，并在 play 末尾执行一次（不会立即执行）。需注意：

• 所有被包含的角色中，Handler 名称都必须唯一
• 如果 play 在执行到 Handler 前失败，Handler 不会运行（必要时使用 meta: flush_handlers）
• Handler 按定义顺序运行，而非按通知顺序
• 多次通知同一个 Handler，只会执行一次

Blocks：使用 block/rescue/always 进行错误处理和回滚——完整的部署与回滚示例请参阅 playbook-patterns.md。优先使用 block/rescue，而不是 ignore_errors: true。

循环：优先使用 loop:，而非较旧的 with_* 查找语法。使用 loop_control.label 让输出更简洁。

条件执行：例如 when: ansible_os_family == "Debian"。对于支持多种操作系统的角色，请按操作系统系列使用条件判断或 include_tasks。Alpine/OpenRC 模式请参阅 playbook-patterns.md。

服务管理：跨发行版角色使用通用的 ansible.builtin.service——它会通过 ansible_service_mgr 自动检测 systemd、OpenRC 和 SysV。只有需要 systemd 专属功能（daemon_reload、scope）时才使用 ansible.builtin.systemd。OpenRC 模式请参阅 playbook-patterns.md。

Shell 配置文件修改：将手动修改 Shell 配置文件的操作转换为 Ansible 时， 优先使用专用且可复用的角色，采用 ansible.builtin.blockinfile、带角色前缀的 默认值，以及专用的 rollout playbook。请参阅 references/operations-and-execution.md； 必须确保该 block 仅在 SSH、当前不在 tmux 中、stdin/stdout 为真实 TTY，且 TERM 可用时执行， 以免劫持自动化操作、scp、rsync 和远程 SSH 命令。

注册结果：register: result_var 会存储 task 输出。使用 when: result_var.stat.exists、result_var.rc == 0 等条件。模式示例请参阅 playbook-patterns.md。

Vault 快速参考

# Encrypt a single variable (inline in YAML)
ansible-vault encrypt_string --prompt --name 'db_password'

# Encrypt an entire file
ansible-vault encrypt group_vars/production/secrets.yml

# Edit encrypted file
ansible-vault edit group_vars/production/secrets.yml

# Run playbook with vault
ansible-playbook site.yml --ask-vault-pass
# Or with a password file (for CI/CD)
ansible-playbook site.yml --vault-password-file ~/.vault_pass

切勿将 Vault 密码以明文形式与仓库一同保存。请使用 --ask-vault-pass、仓库外的密码文件，或从密钥管理器获取密码的 Vault 脚本。

不要这样写

• command: apt-get install -y nginx（使用 ansible.builtin.apt）
• shell: systemctl restart nginx（使用 ansible.builtin.systemd）
• shell: useradd deploy（使用 ansible.builtin.user）
• 对敏感文件使用 copy 却不设置 mode:（默认值取决于 umask，无法预测）
• 源文件没有 .j2 扩展名却使用 template
• 使用 ignore_errors: true 却没有注释说明原因（改用 block/rescue）
• 盲目将 with_items 改写为 loop：两者都受支持；简单列表优先使用 loop，需要时用 flatten(1) 保留单层展平行为
• 不加引号的裸写 {{ var }}（YAML 会将其解析为字典起始符）
• 设置 gather_facts: true 却从不使用 facts（每台主机会浪费 5–15 秒）
• 没有 name: 的 task（虽然合法，但输出难以阅读）
• 在生产环境的 playbook 中使用 state: latest（结果不确定——请锁定版本）

---

Roles 与 Collections

详细了解角色结构、Collection 结构、Galaxy 模式和 Molecule 测试工作流，请阅读 references/roles-and-collections.md。

• 每个角色只负责一项职责。
• 用户可调整的值应放在 defaults/main.yml 中，而不是 vars/main.yml 中。
• 全程使用 FQCN。
• 为角色变量添加前缀，避免冲突。
• 对于包含测试场景的角色，必须进行 Molecule 幂等性检查，这不是可有可无的优化。

---

运维

• 阅读 references/operations-and-execution.md，了解清单布局、ansible.cfg、执行环境、CI/CD 集成和 ansible-navigator。
• 按环境拆分清单。
• 修改现有清单时，优先使用 YAML 清单，而非旧版 INI。
• 将 pipelining = True、事实缓存和回调配置视为标准生产默认设置。
• 使用执行环境进行可重复的本地和 CI 运行。
• 在 references/vault-and-secrets.md 中维护 Vault 用法；机密必须保持加密、添加前缀，并使用 no_log: true 包装。

---

合规

阅读 references/compliance.md，了解 PCI-DSS 4.0 要求与 Ansible 控制的完整映射、CIS 基准自动化和加固模式。

• Ansible 负责操作系统和服务的强制执行，而非应用层安全审查。
• CIS 和 PCI 控制应作为角色和模板的输入，而不是盲目套用的默认设置。
• 在大范围推广前，先在预发布环境中测试基准加固。
• 通过回调插件、AWX/AAP 活动流或 CI 工件保留审计证据。

---

弃用项和重大变更

ansible-core 2.20

移除项（已移除）：

• smart 传输值——请明确选择 ssh 或 paramiko
• Galaxy v2 API 支持——Galaxy 服务必须支持 v3
• PARAMIKO_HOST_KEY_AUTO_ADD 和 PARAMIKO_LOOK_FOR_KEYS 配置键
• encrypt 工具中的 passlib_or_crypt API

弃用项（将在 2.24 中移除）：

• INJECT_FACTS_AS_VARS 默认值为 True，但之后将改为 False。请通过 ansible_facts['hostname'] 访问事实，而不要使用 ansible_hostname。
• ansible.module_utils._text 导入项（to_bytes、to_native、to_text）——请改用 ansible.module_utils.common.text.converters
• vars 内部变量缓存

ansible-core 2.19（上一版本）

• **数据标记（Data Tagging）**全面改造：错误报告有所改进，但部分循环模板因此失效（GitHub issue #85605）。升级后若循环因类型错误而失败，请检查是否与原生 Jinja2 类型处理冲突。

CalVer 迁移

所有 Ansible DevTools 项目（molecule、ansible-lint、ansible-navigator、tox-ansible）均于 2024 年从 SemVer 切换到 CalVer（YY.MM.MICRO）。请勿因版本号跳跃而困惑（例如，ansible-lint 从 6.x 升至 26.x）。

---

安全注意事项

需要了解的 CVE

CVE	严重性	描述	缓解措施
CVE-2024-11079	低	Hostvars 绕过不安全内容保护，允许通过模板内容执行任意代码	升级至 ansible-core >= 2.16.14、2.17.7 或 2.18.1
CVE-2024-8775	中	Vault 加密的变量在未设置 no_log 时通过 include_vars 以明文形式泄露	为所有处理机密的任务添加 no_log: true
CVE-2025-14010	中	community.general 在详细输出中暴露 Keycloak 凭据	升级至 community.general >= 12.0.0（或 11.4.1 / 10.7.6），即 ansible 软件包 >= 12.2.0
CVE-2025-49520	高	EDA 在 Git URL 中存在已认证参数注入漏洞（命令执行）	修补 AAP/EDA
CVE-2025-49521	高	EDA 可通过 Git 分支/refspec 进行模板注入（命令执行）	修补 AAP/EDA

检查日期：2026-09-10：CVE-2026-16493 是一项严重性较高的集合安装参数注入漏洞，未被针对 CVE-2026-11332 的角色安装修复所覆盖。请检查 requirements.yml 中的 Git 源；使用可信的 Galaxy/Automation Hub 源和供应商已修复的构建版本。检索到的供应商记录未明确上游修复版本范围，因此不要假设仅凭目标版本固定就能证明漏洞已修复。

供应链

• Galaxy 没有软件包签名或哈希校验。2025 年的一项学术研究在 482 个 Galaxy 仓库中发现了 45 条存在漏洞的依赖链，38%–54% 的代码重叠会传播漏洞。
• 在 requirements.yml 中固定集合版本。对于生产关键型集合，优先选择 Automation Hub（Red Hat 认证），而不是 Galaxy。
• 在 CI/CD 中将 GitHub Actions 固定到提交 SHA（而非可变标签）。
• 像扫描任何容器镜像一样，扫描 EE 镜像中的 CVE。

AI 生成的 playbook 风险

• AI 工具会幻觉出模块名称和参数。请确认每个模块都存在于目标集合版本中。
• AI 很少会在处理机密信息的任务中添加 no_log: true。
• 如果存在相应模块，AI 仍会生成非幂等的 command/shell 任务。
• AI 会使用裸模块名称，而不是 FQCN。
• Slopsquatting：AI 可能会推荐不存在的 Galaxy 角色或集合。将其添加到 requirements.yml 前，请先在 Galaxy 上确认。

---

参考文件

• references/playbook-patterns.md - 常见自动化工作的 playbook 和任务模式
• references/production-checklist.md - playbook、角色、运维和 PCI-DSS 检查清单；完成任何构建或审查前都应运行
• references/roles-and-collections.md - 角色结构、集合结构、Galaxy 模式和 Molecule 工作流
• references/operations-and-execution.md - 清单布局、ansible.cfg、执行环境、CI/CD 集成和 navigator 用法
• references/vault-and-secrets.md - Vault 用法、机密信息处理和外部机密管理器集成
• references/compliance.md - 面向 PCI-DSS 和 CIS 的加固指南

---

输出约定

完整约定请参阅 references/output-contract.md。

• Skill 名称： ANSIBLE
• 交付物类别： audits
• 模式： 有条件。调用以分析、审查、审计或改进现有仓库内容时，请遵循 references/output-contract.md 中的报告长度和证据规则，并将交付物写入 docs/local/audits/ansible/<YYYY-MM-DD>-<slug>.md。调用以回答问题、讲解概念、构建新产物或生成内容时，可自由作答，不受此约定限制。
• 严重性级别： P0 | P1 | P2 | P3 | info（参阅共享约定；仅用于审计/审查模式）。

相关技能

• terraform - 用于配置基础设施（VM、网络、云资源）。Ansible 会配置 Terraform 创建的内容。第 1 天的配置 = terraform；第 2 天的配置 = ansible。
• kubernetes - 用于 K8s 清单、Helm 图表和集群架构。Ansible 可通过 kubernetes.core 集合部署到 K8s，但清单设计属于 kubernetes 技能的范畴。
• docker - 用于 Dockerfile 和 Compose 模式。Ansible 可通过 community.docker 管理容器，但镜像构建和 Compose 设计属于 docker 技能的范畴。
• databases - 用于引擎配置（postgresql.conf、pg_hba.conf）。Ansible 可自动部署这些配置；调优决策由 databases 技能负责。
• ci-cd - 用于流水线设计。Ansible 可由 CI/CD 流水线调用，但流水线结构（阶段、作业、缓存）属于 ci-cd 技能的范畴。
• security-audit - 用于审计 Ansible playbook 中的凭据泄露、Vault 误用或 Galaxy 依赖项中的供应链风险。
• debian-ubuntu - 用于自动化场景之外有关 Debian/Ubuntu/Mint 的操作系统级管理问题。
• rhel-fedora - 用于自动化场景之外有关 RHEL/Fedora/CentOS 的操作系统级管理问题。
• kali-linux - 用于自动化场景之外的 Kali Linux 管理。
• arch-linux - 用于自动化场景之外有关 Arch Linux / CachyOS 的操作系统级管理问题。

---

规则

以下要求不可妥协。违反任何一条都属于缺陷。

1. 默认保持幂等。 每项任务都必须可安全地重复运行。command/shell 任务需要设置 creates/removes 或 changed_when。
2. 对机密设置 no_log: true。 任何处理密码、令牌、API 密钥或敏感数据的任务都必须设置。CVE-2024-8775 已证明遗忘此项的代价。
3. 使用 Vault 管理机密。 不要将机密以明文写入 group_vars，不要在清单中设置 ansible_ssh_pass，也不要在 playbook 中使用环境变量。
4. 使用 Molecule 测试。 共享角色或非简单角色都应配置 Molecule 场景，包含 converge、幂等性检查，以及对角色可观察结果的验证，而不是验证每项任务。
5. 固定集合版本。 在 requirements.yml 和 EE 定义中固定版本。未固定版本的集合会带来供应链风险。
6. 确保 ansible-lint 检查通过。 使用生产配置文件。在 CI 中运行。每次变更都要检查。
7. 为每个环境分别设置清单。 生产、预发布、开发环境各自独立。绝不要使用单一清单并通过 --limit 选择环境。
8. 应用前运行 --check --diff。 在应用前审查变更内容，尤其是在 CI/CD 中。