---
tags: [ansible, playbook, infra, automation, iaas]
create time: 2026-07-04 13:30
---

# Ansible Playbook 基础

## 概述

Ansible 是一个无 Agent 的自动化运维工具，通过 SSH 协议远程管理主机。**Playbook** 是 Ansible 的核心概念——用 YAML 描述的自动化任务编排文件。xinfra 的进阶目标中要求使用 Ansible Playbook 部署 MySQL Server、PostgreSQL 和 Redis Cluster，这是实现数据库层**基础设施即代码（IaC）**的关键技能。

## 核心概念

### 工作原理

```mermaid
graph LR
    Controller[控制节点 / Laptop or CI Host]
    SSH[SSH 连接]
    Nodes[(被控主机列表)]
    Controller -->|读取 Playbook YAML| SSH
    SSH -->|推送临时模块脚本| Nodes
    Nodes -->|返回 JSON 结果| Controller
```

关键特点：
- **无 Agent**：不需要在被控机器上安装任何软件，仅依赖 Python + SSH
- **幂等性（Idempotent）**：同一个 Playbook 执行多次效果相同，不会重复创建或修改
- **模块化**：每个操作封装为独立模块（如 `ansible.builtin.shell`、`ansible.builtin.yum`、`ansible.builtin.template`）

### 特权提升（Become）

`become` 是 Ansible 的 **跨平台权限提升机制**，允许非 root 用户登录主机后切换到目标账户执行任务。不改变初始 SSH 连接会话——临时模块脚本仍通过原始身份推送，但实际运行时切换身份。

```yaml
# Playbook 级别 — 所有任务以 root 执行
- hosts: all_mysql_servers
  become: yes

# Task 级别 — 精细控制
- name: Run command as postgres user
  ansible.builtin.command: /usr/bin/pg_dump mydb
  become: yes
  become_user: postgres
  become_method: sudo           # su | doas | pfexec (OpenSolaris)
  become_flags: '-s /bin/sh'   # 额外标志位
```

| 参数 | 作用 | 示例值 |
|------|------|--------|
| **become** | 是否启用权限提升 | `yes` / `true` |
| **become_user** | 切换的目标用户 | `root`, `postgres`, `apache` |
| **become_method** | 底层实现方式 | `sudo`（默认）, `su`, `pfexec` |
| **become_flags** | 传递给底层方法的附加参数 | `-s /bin/sh` |

> [!warning] 安全注意事项
> - **密码不能明文存储**：敏感凭据应通过 Ansible Vault 加密（见延伸阅读链接）
> - **Pipelining**：在 `/etc/ansible/ansible.cfg` 中开启 `pipelining = True`，可避免临时文件写入磁盘，减少安全风险
> - **每台主机仅能启用一种方法**：同时配置 `sudo` + `su` 会导致冲突
> - **最佳实践**：SSH 连入时已有较高权限 → 按需向下切换，比全程用 root 更安全

### Playbook 结构骨架

```yaml
- hosts: all_mysql_servers
  become: yes                        # 提升 root 权限执行
  vars:                              # 变量定义
    mysql_port: 3306
    mysql_data_dir: /data/mysql
  roles:                             # 引用角色
    - common-setup                   # 系统级准备
    - install-mysql                  # MySQL 安装
  tasks:                             # 显式任务列表
    - name: Ensure MySQL is running
      ansible.builtin.service:       # 推荐写全称（命名空间规范）
        name: mysqld
        state: started
      notify: restart mysql          # 触发 handler
  handlers:                          # 响应通知动作
    - name: restart mysql
      ansible.builtin.service:
        name: mysqld
        state: restarted
```

### 关键概念对照

| 概念 | 作用 | 类比 |
|------|------|------|
| **Hosts** | 指定目标机器组（Inventory 中定义） | SSH target |
| **Tasks** | 按顺序执行的操作 | 脚本命令 |
| **Roles** | 可复用的任务集合 | 函数库 |
| **Handlers** | 监听通知的触发器（常用于重启服务） | 事件回调 |
| **Modules** | 单功能执行单元 | 子命令 |
| **Inventory** | 被控主机清单 | SSH config 中的 host |

### 变量优先级体系（由低到高）

```yaml
# 变量加载顺序（低 → 高）：
#   1. host_vars/<hostname>/all.yml     — 特定主机变量
#   2. group_vars/<group>/all.yml       — 主机组共享变量
#   3. roles/<role>/defaults/main.yml   — 角色默认值（可被覆盖）
#   4. Playbook 顶层 vars               — Playbook 内联变量
#   5. extra_vars (-e 参数)             — 运行时传入，优先级最高
```

> [!tip] 为什么需要多级变量？
> 同一个 `mysql_port` 在开发环境可能是 `3307`，生产环境是 `3306`。**group_vars 按环境隔离 + defaults 提供安全兜底**——这是大型 Ansible 项目中最常用的变量管理模式。

### 变量引用语法

```yaml
# YAML 文件中用双大括号引用
- name: Set MySQL port
  debug:
    msg: "MySQL is running on port {{ mysql_port }}"

# 在模板文件（.j2）中同样使用
port = {{ mysql_port }}

# 支持字典访问和索引
- name: Access nested variables
  debug:
    msg: "{{ db_config.host }},{{ db_config.credentials.password }}"
```

### MySQL 部署的角色拆分示例

一个典型的 MySQL 部署 Playbook 会拆成多个 Role：

```
roles/
├── common-setup/
│   ├── tasks/main.yml       # 时间同步、内核参数调优、防火墙规则
│   └── templates/            # 系统级配置文件模板
├── install-mysql/
│   ├── tasks/main.yml       # 安装、配置主从复制
│   └── files/               # 二进制包或 RPM 安装包
└── config-mysql/
    ├── tasks/main.yml       # 编写 my.cnf（Jinja2 模板）
    └── templates/my.cnf.j2  # 根据变量动态生成配置
```

每个 Role 可以独立测试和复用，不同服务的安装只需替换中间两个 Role。

### Jinja2 模板实战

```ini
# my.cnf.j2
[mysqld]
port = {{ mysql_port | default(3306) }}
datadir = {{ mysql_data_dir | default('/var/lib/mysql') }}
server-id = {{ inventory_hostname | regex_replace('\\D', '') | int }}
{% if role == 'master' %}
log-bin = mysql-bin
binlog-format = ROW
{% elif role == 'slave' %}
read-only = 1
relay-log = relay-bin
{% endif %}
```

> [!tip] 为什么需要 Jinja2 模板？
> 同一套 Playbook 要用于 Master 和 Slave，它们的配置有差异。**模板 + 变量注入**比硬编码多个 Playbook 更灵活——这也是 IaC 的核心思想：**一套代码，多种环境**。

## 控制流

### 循环（Loops）

Ansible 推荐使用简洁的 `loop` 语法替代旧式的 `with_items`。`loop` 在 2.5 版本引入，功能等价于 `with_list`，但更简洁且与 `lookup` 兼容更好。

#### 基础用法

```yaml
- name: Install multiple packages
  ansible.builtin.yum:
    name: "{{ item }}"
    state: present
  loop:
    - vim
    - curl
    - git
    - wget

# 字典列表循环 — 适合批量创建用户/配置
- name: Create database users
  community.mysql.mysql_user:
    name: "{{ item.name }}"
    password: "{{ item.password }}"
    priv: "{{ item.priv }}"
    state: present
  loop: "{{ db_users }}"   # 引用 vars 中定义的变量列表
```

#### 字典迭代（dict2items）

当需要遍历 YAML 字典时，用 `dict2items` 将其转为 `[{"key": ..., "value": ...}, ...]` 结构：

```yaml
- name: Configure servers from dictionary
  ansible.builtin.debug:
    msg: "{{ item.key }}: IP={{ item.value.ip_address }}, role={{ item.value.role }}"
  loop: "{{ server_configs | dict2items }}"
  vars:
    server_configs:
      web_01:
        ip_address: "10.1.1.50"
        role: "frontend"
      web_02:
        ip_address: "10.1.1.51"
        role: "backend"
```

> [!tip] query vs lookup
> `loop` 要求返回一个 list。使用 lookup 插件时，推荐用 `query`（2.5+），它保证返回列表；如果用 `lookup`，需加 `wantlist=True`：
> ```yaml
> loop: "{{ query('inventory_hostnames', 'all') }}"
> # 或
> loop: "{{ lookup('inventory_hostnames', 'all', wantlist=True) }}"
> ```

#### 循环控制（loop_control）

```yaml
- name: Create cloud instances with delay
  digital_ocean:
    name: "{{ item.name }}"
    state: present
  loop:
    - { name: server1, disk: 3gb }
    - { name: server2, disk: 4gb }
  loop_control:
    label: "{{ item.name }}"     # 自定义输出标识（避免冗长日志）
    pause: 3                     # 每项之间等待 N 秒（避免瞬时并发压力）
    loop_var: outer_item         # 指定外层循环变量名（嵌套循环防冲突）
```

#### 自动重试（until 循环）

`until` 不是用来遍历数据的——它是 **轮询重试** 模式，适用于可能暂时失败、最终会成功的操作（如等待服务启动）：

```yaml
- name: Wait for service to be ready
  shell: /usr/bin/check_service_ready
  register: result
  until: result.stdout.find("ready") != -1
  retries: 5              # 最大尝试次数
  delay: 10               # 每次间隔秒数
```

注册变量在循环中的结构是嵌套的：`{{ my_loop.results[0].stdout }}`、`{{ my_loop.results[1].rc }}` 等，后续用 `when: item.rc != 0` 过滤即可。

> [!warning] with_items → loop 迁移注意
> `with_items` 有**隐式扁平化**行为：`with_items: [1, [2,3], 4]` 会展平为 `[1, 2, 3, 4]`。切换到 `loop` 后需手动处理：
> ```yaml
> loop: "{{ [1, [2, 3], 4] | flatten(1) }}"
> ```

### 条件判断（when）

```yaml
- name: Configure slave replication
  template:
    src: my.cnf.j2
    dest: /etc/my.cnf
  when: inventory_hostname in groups['mysql_slaves']

# 复杂条件
- name: Only on CentOS 7
  debug:
    msg: "CentOS detected"
  when:
    - ansible_os_family == "RedHat"
    - ansible_distribution_major_version == "7"
```

> [!warning] 何时不用 when？
> 如果 `when` 只是过滤几行数据，优先在 Jinja2 模板内部用 `{% if %}` 处理，而不是写一个全量任务再套 `when`——后者会在所有目标主机上都执行一次无意义的模块调用。

### notify / handlers 机制详解

```yaml
tasks:
  - name: Update Nginx config
    ansible.builtin.template:
      src: nginx.conf.j2
      dest: /etc/nginx/nginx.conf
    notify: reload nginx       # ← 仅设置"标记"，不立即执行

handlers:
  - name: reload nginx
    ansible.builtin.service:
      name: nginx
      state: reloaded           # ← 仅在 Playbook 阶段结束时触发
```

> [!info] notify 的关键语义
> 即使多个 task 都 `notify` 同一个 handler，handler 也只会**在每个 Play 结束后执行一次**。这正是幂等性设计的一部分——避免重复重启服务。

### 结果捕获与错误处理

```yaml
# register — 将命令输出保存到变量
- name: Check if MySQL data dir exists
  ansible.builtin.stat:
    path: /data/mysql
  register: mysql_data_check

- name: Initialize data dir if missing
  ansible.builtin.file:
    path: /data/mysql
    state: directory
    owner: mysql
    group: mysql
  when: not mysql_data_check.stat.exists

# ignore_errors — 允许任务失败不中断 Playbook
- name: Try to stop already-stopped service
  ansible.builtin.service:
    name: mysqld
    state: stopped
  ignore_errors: yes

# failed_when — 自定义失败判定逻辑
- name: Check API health
  ansible.builtin.uri:
    url: http://localhost:8080/health
  register: health_check
  failed_when: "'unhealthy' in health_check.content"

# set_fact — 动态设置变量供后续任务使用
- name: Capture private IP
  ansible.builtin.set_fact:
    node_private_ip: "{{ ansible_default_ipv4.address }}"
```

> [!tip] register 的经典使用场景
> `stat` 模块检查文件存在 → `when` 判断决定是否创建 → 这就是 **"先查后做"** 的 Ansible 范式，完美体现幂等性原则。

### 状态控制（changed_when / any_errors_fatal）

除了 `failed_when` 外，Ansible 还允许通过 **`changed_when`** 精确控制任务的变更状态——这直接影响统计报告和 handler 触发：

```yaml
# ❌ command 永远是 "changed"，即使数据库连接无变化
- name: Check DB connection
  command: mysql -e "SELECT 1"

# ✅ 仅在真正有变更时标记为 changed
- name: Check DB connection
  shell: mysql -e "SELECT 1"
  register: db_check
  changed_when: "'ERROR' in db_check.stdout"

# 强制不报告变更（常用于健康检查类任务）
- name: Health check endpoint
  uri:
    url: http://localhost:8080/health
  changed_when: false
```

| 参数 | 作用域 | 说明 |
|------|--------|------|
| **ignore_errors** | Task 级 | 失败继续执行，不中断 Play |
| **ignore_unreachable** | Play 级 | 跳过网络不可达的主机，继续其他主机 |
| **any_errors_fatal** | Play/Block 级 | 任一主机报错即终止全部执行 |
| **max_fail_percentage** | Play 级 | 失败超过阈值（%）时停止 |
| **changed_when** | Task 级 | 条件性覆盖 "已变更" 报告 |
| **failed_when** | Task 级 | 条件性覆盖 "失败" 判定 |

### Block / Rescue / Always — 结构化异常处理

这是编程中 `try/catch/finally` 的 Ansible 等价物，适合需要 **原子化操作 + 自动回滚** 的场景：

```yaml
- name: Deploy application with rollback
  block:
    - name: Backup current release
      archive:
        path: /opt/app/current
        dest: /opt/backups/release-$(date +%s).tar.gz
      register: backup_result

    - name: Extract new version
      unarchive:
        src: new-app-v2.tar.gz
        dest: /opt/app/releases/v2
        remote_src: yes

    - name: Symlink to active release
      file:
        src: /opt/app/releases/v2
        dest: /opt/app/current
        state: link

  rescue:
    - name: Log failure details
      debug:
        msg: "Task '{{ ansible_failed_task.name }}' failed on {{ inventory_hostname }}"

    - name: Rollback to previous release
      file:
        src: /opt/app/releases/v1
        dest: /opt/app/current
        state: link
      when: backup_result is succeeded   # 仅当备份成功时才尝试还原

  always:
    - name: Notify deployment team
      ansible.builtin.command: >
        curl -X POST https://hooks.slack.com/deploy-webhook
        -d '{"text":"Deployment {{ ansible_failed_task.name if ansible_failed_task else 'succeeded' }} on {{ inventory_hostname}}"}'
      changed_when: false
```

> [!info] 语义对比表
>
> | 编程概念 | Ansible 关键字 | 触发条件 |
> |----------|---------------|---------|
> | `try {}` | `block:` | 正常任务流，始终执行 |
> | `catch {}` | `rescue:` | 仅当前置任务返回 `failed` 时触发 |
> | `finally {}` | `always:` | 无论成败均执行 |
>
> - **Rescue 中的恢复若成功，Play 会继续**——但统计日志仍记录一次故障
> - **语法错误、断连等情况不会触发 Rescue**，与编程语言不同
> - **Handler 可以在 Rescue 中被调用**（通过元数据命令触发）

## 常用模块速查

> [!info] 命名空间规范（Namespace Prefix）
> Ansible 2.10+ 开始引入 `collections` 概念，推荐始终使用前缀格式：
> - `ansible.builtin.copy` — 内置模块
> - `community.general.selinux` — 社区集合
> - 现代 Playbook 中优先写全称；如果省略前缀，Ansible 会按内置 → 已安装的集合顺序自动匹配。

| 模块 | 用途 | 关键参数 |
|------|------|---------|
| **ansible.builtin.copy** | 本地文件复制到远程 | `src`, `dest`, `owner`, `mode` |
| **ansible.builtin.template** | Jinja2 模板渲染后复制 | `src (.j2)`, `dest`, `owner`, `mode` |
| **ansible.builtin.file** | 管理文件/目录权限和属性 | `state: touch/file/directory/link/absent`, `mode` |
| **ansible.builtin.yum** / **ansible.builtin.apt** | 包管理 | `name`, `state: present/installed/latest/absent` |
| **ansible.builtin.service** | 管理服务生命周期 | `name`, `state: started/stopped/restarted/reloaded` |
| **ansible.builtin.lineinfile** | 确保某行存在或不存在于文件中 | `path`, `line`, `state`, `regexp` |
| **ansible.builtin.replace** | 正则替换文件内容 | `path`, `regexp`, `replace` |
| **ansible.builtin.command** / **ansible.builtin.shell** | 执行命令（慎用） | `cmd`, `chdir` |
| **ansible.builtin.get_url** / **ansible.builtin.uri** | HTTP 下载 / API 调用 | `url`, `dest`, `method`, `status_code` |
| **ansible.builtin.user** | 管理系统用户 | `name`, `state`, `groups`, `shell` |
| **ansible.builtin.cron** | 管理 crontab | `name`, `minute`, `job`, `state` |
| **ansible.builtin.debug** | 调试输出 | `msg`, `var` |
| **ansible.builtin.stat** | 检查文件/路径属性 | `path`, returns `.stat.exists` |
| **community.mysql.mysql_user** | MySQL 用户管理 | `name`, `password`, `priv`, `state` |
| **community.postgresql.postgresql_user** | PostgreSQL 用户管理 | `name`, `password`, `role_attr` |

> [!warning] command vs shell 的选择
> `command` 不经过 Shell 解释器（更安全，推荐优先使用），`shell` 才支持管道 `\|`、重定向 `>`、变量扩展 `$VAR`。**能用模块完成的操作绝不碰 command/shell**。

## 常见陷阱与最佳实践

### 1. 不要跳过 `state` 检查

错误写法：
```yaml
- ansible.builtin.command: systemctl start mysqld    # ❌ 每次都会尝试启动，即使已在运行
```

正确写法：
```yaml
- ansible.builtin.service:                           # ✅ Ansible 自带的 service 模块会检查当前状态
    name: mysqld
    state: started
```

### 2. Inventory 分层管理

把开发、测试、生产环境的机器分开管理：
```ini
# inventory/prod
[mysql_prod]
mysql-prod-01 ansible_host=10.0.1.11
mysql-prod-02 ansible_host=10.0.1.12

[redis_prod]
redis-prod-01 ansible_host=10.0.1.21
```

### 3. 首次运行时务必先 Dry Run

```bash
# --check 只做预演，不实际执行
ansible-playbook deploy.yml --check --diff
```

### 4. 警惕 shell/command 失去幂等性

```yaml
# ❌ 每次运行都会在日志末尾追加一行
- ansible.builtin.shell: echo "deployed" >> /tmp/deploy-history

# ✅ 用 file module 保证状态一致性
- ansible.builtin.file:
    path: /tmp/deploy-marker
    state: touched
    modification_time: preserve
```

## 延伸阅读

- [[technical/xinfra-preview/k8s-rke2-fundamentals]] — K8s 内的实例 vs Ansible 管理的裸机/VM
- [[technical/xinfra-preview/cachecloud-overview]] — CacheCloud 管 Redis，Ansible 负责底层部署
- [[technical/xinfra-preview/cloud-dm-overview]] — Ansible 部署的 MySQL 由 CloudDM 做 SQL 审核
- [官方 Playbook 指南](https://github.com/ansible/ansible-documentation/tree/devel/docs/docsite/rst/playbook_guide) — Ansible 文档源码，涵盖从入门到高级语法的全部章节
- https://www.ansible.com/docs — Ansible 官方文档入口
- [Ansible Vault 文档](https://docs.ansible.com/ansible/latest/cli/ansible-vault.html) — 加密敏感凭据（密码、密钥），解决 Become 中的安全合规问题
- [入门教程](https://www.cnblogs.com/easonscx/p/10622781.html) — Ansible 基础用法参考