Playbook 用 YAML 描述目标状态。可维护性来自清晰命名、幂等模块、合理变量范围和失败处理，而不是把 shell 脚本逐行搬进 YAML。
## 基本 Playbook
```yaml
- name: Configure web servers
hosts: web
become: true
serial: 2
tasks:
- name: Install nginx
ansible.builtin.package:
name: nginx
state: present
- name: Deploy configuration
ansible.builtin.template:
src: nginx.conf.j2
dest: /etc/nginx/nginx.conf
owner: root
group: root
mode: '0644'
validate: 'nginx -t -c %s'
notify: Restart nginx
handlers:
- name: Restart nginx
ansible.builtin.service:
name: nginx
state: restarted
```
Handler 只在通知且任务发生变更时运行。模板使用 validate 可在覆盖正式配置前检查语法。
## 变量
变量可来自 role defaults、Inventory、host_vars、group_vars、Play、include、事实和 extra-vars，优先级复杂。团队应约定每类变量只放一个位置；Role 可覆盖参数放 defaults，环境差异放 Inventory，敏感值加密。
以 {{ variable }} 开头的 YAML 值要整体加引号。使用 ansible-playbook ... -e @vars.yml 比复杂命令行字符串更安全和清晰，但文件仍需权限保护。
## Blocks 与错误处理
```yaml
- block:
- name: Deploy new version
ansible.builtin.include_role:
name: app_deploy
rescue:
- name: Roll back
ansible.builtin.include_role:
name: app_rollback
always:
- name: Collect status
ansible.builtin.command: /opt/app/bin/status
changed_when: false
```
rescue 不是忽略错误。回滚任务也可能失败，关键操作应使用 any_errors_fatal、max_fail_percentage、serial 和明确的健康检查限制影响范围。
## Ansible Vault
```bash
ansible-vault create group_vars/prod/vault.yml
ansible-vault edit group_vars/prod/vault.yml
ansible-playbook site.yml --vault-id prod@prompt
```
Vault 加密静态数据，不会自动阻止任务把 Secret 打到日志。敏感任务设置 no_log: true，并限制 Vault 密码文件权限和访问者。更大规模可集成外部 Secret 系统。
## 调试
```bash
ansible-playbook site.yml --syntax-check
ansible-playbook site.yml --list-hosts --list-tasks
ansible-playbook site.yml --check --diff --limit web01
ansible-playbook site.yml -vv
```
使用 debug 输出必要变量，避免整个 hostvars 和 Secret。register 后先参考模块文档 RETURN 结构，不要猜字段。
## 生产发布
- serial 小批量执行。
- pre_tasks 检查容量与依赖。
- 每批完成后执行健康检查。
- 失败立即停止，不在所有主机继续。
- 部署产物使用不可变版本。
- 回滚 Playbook 与发布一起测试。
参考：https://docs.ansible.com/projects/ansible/latest/playbook_guide/