creating-ansible-playbooks

创建 Ansible Playbook

概述

生成可用于生产环境的 Ansible playbook、角色和清单，用于基础设施自动化。支持通过基于 SSH 的无 Agent 自动化，在整组机器上预配服务器、部署应用、配置服务和强制执行目标状态。

前提条件

• 已安装 Ansible 2.14+（ansible --version）
• 可通过基于密钥的身份验证 SSH 访问目标主机
• 控制节点和受管节点上均安装了 Python 3.9+
• 目标主机清单（IP 或主机名）
• 如果要配置系统级资源，则需要权限提升凭据（sudo）
• 已安装 ansible-lint，用于验证 playbook

说明

1. 扫描项目中现有的 Ansible 文件（ansible.cfg、inventory/、roles/、group_vars/），了解当前结构
2. 确定自动化目标：服务器预配、应用部署、配置管理或安全加固
3. 创建结构规范的 playbook YAML：hosts、become、vars、tasks、handlers
4. 按照标准目录布局（tasks/、handlers/、templates/、defaults/、vars/、meta/）将可复用逻辑提取到角色中
5. 在 group_vars/ 和 host_vars/ 中定义环境专属变量，并将密钥保存在由 vault 加密的文件中
6. 对因环境而异的配置文件使用 Jinja2 模板
7. 为配置更改触发的服务重启添加处理程序
8. 使用 ansible-lint 和 ansible-playbook --check --diff（试运行）验证 playbook
9. 连续运行 playbook 两次以测试幂等性，并确认第二次运行不会产生更改

输出

• Ansible playbook（.yml），包含结构化的任务、处理程序和变量
• 遵循 Ansible Galaxy 结构的角色目录
• 用于动态配置文件的 Jinja2 模板（.j2）
• 包含主机组的清单文件（INI 或 YAML）
• 用于区分环境的 group_vars/ 和 host_vars/
• 包含连接和权限提升设置的 ansible.cfg

错误处理

错误	原因	解决方案
unreachable: Failed to connect to host	SSH 连接失败或主机/端口错误	使用 ansible -m ping 验证 SSH 密钥、主机 IP，并确认端口 22 已开放
权限提升时出现 permission denied	sudo 密码缺失或错误	添加 --ask-become-pass，或在 vault 中配置 ansible_become_password
undefined variable	未在 vars、defaults 或清单中定义变量	检查变量优先级；在 defaults/main.yml 或 group_vars/ 中定义变量
ansible-lint: syntax-check failed	YAML 语法错误或使用了已弃用的模块	运行 ansible-lint -v 并修复报告的问题；替换已弃用的模块
每次运行都会显示 changed（不具备幂等性）	使用 command/shell 时未设置 creates/removes 保护条件	添加 creates: 参数，或改用专用模块（copy、template、file）

示例

• “创建一个 Ansible playbook，用于预配安装了 Nginx、Certbot 和仅允许 80/443 端口的防火墙的 Ubuntu 22.04 服务器。”
• “生成一个角色，用于部署 Python Flask 应用，并配置 Gunicorn、systemd 服务文件和日志轮转。”
• “编写一个 Ansible playbook，为所有服务器加固 SSH 配置：禁用 root 登录、强制使用密钥身份验证并设置空闲超时。”

资源

• Ansible 文档：https://docs.ansible.com/ansible/latest/
• Ansible Galaxy 角色：https://galaxy.ansible.com/
• Ansible Lint 规则：https://ansible.readthedocs.io/projects/lint/rules/
• 最佳实践指南：https://docs.ansible.com/ansible/latest/tips_tricks/ansible_tips_tricks.html