当前位置：首页 > news >正文

Ansible 配置Playbook文件格式、关键字和语法详解

news 来源：原创 2025/6/1 22:29:32

Ansible Playbook 使用 YAML 格式编写，通过定义任务流程实现自动化。以下是 Playbook 的核心结构、关键字和语法详解：

一、Playbook 基础结构

1. 基本框架

---
- name: Play 1 Description  # Play 的名称hosts: target_host_group  # 目标主机组（来自 Inventory）become: yes               # 是否提权（sudo）vars:                     # 定义变量http_port: 80tasks:                    # 任务列表- name: Task 1          # 任务名称module_name:          # 模块名称（如 apt, copy）module_parameter: value- name: Play 2 Description  # 另一个 Play（按顺序执行）hosts: another_grouptasks: [...]

二、核心关键字详解

1. Play 级别关键字

关键字	说明
`name`	Play 的描述性名称（可选，但推荐使用）
`hosts`	目标主机组或主机模式（如 `web_servers` 或 `192.168.1.*`）
`become`	是否提权（默认 `no`），等同于 `sudo`
`vars`	定义 Play 级变量
`vars_files`	引入外部变量文件（如 `vars/main.yml`）
`tasks`	定义任务列表
`handlers`	定义处理器（由任务触发，如重启服务）
`roles`	引入角色（模块化复用代码）
`pre_tasks`	在 `tasks` 前执行的任务列表
`post_tasks`	在 `tasks` 后执行的任务列表
`environment`	设置环境变量
`any_errors_fatal`	任一任务失败时终止整个 Play（默认 `no`）

2. Task 级别关键字

关键字	说明
`name`	任务的描述（必填，清晰描述任务作用）
`module`	调用的 Ansible 模块（如 `apt`, `copy`）
`args`	模块参数（替代行内参数写法，适用于复杂场景）
`when`	条件判断（仅在条件满足时执行任务）
`loop`	循环执行任务（替代旧版 `with_items`）
`register`	将任务结果保存到变量
`ignore_errors`	忽略任务失败（默认 `no`）
`changed_when`	定义任务何时标记为 "changed" 状态
`failed_when`	定义任务何时标记为 "failed" 状态
`tags`	为任务打标签，方便选择性执行
`retries`	任务失败重试次数（常与 `until` 结合）
`delay`	重试间隔时间（秒）
`until`	重试直到条件满足

3. Handler 关键字

handlers:- name: restart_nginxservice:name: nginxstate: restarted

由任务中的 notify 触发，按定义顺序执行。
仅在所有任务执行完毕后触发一次（即使被多次通知）。

三、语法细节与示例

1. YAML 格式要求

缩进：使用 2 个空格（非 Tab）。
列表：以 - 开头。
字符串：可省略引号，但包含特殊字符时需用 " 或 ' 包裹。

2. 变量定义与引用

vars:package_name: nginxconfig_path: "/etc/{{ package_name }}/nginx.conf"tasks:- name: Install Packageapt:name: "{{ package_name }}"

3. 条件判断 (`when`)

- name: Install EPEL on CentOSyum:name: epel-releasestate: presentwhen: ansible_os_family == 'RedHat'

4. 循环 (`loop`)

- name: Add Usersuser:name: "{{ item }}"state: presentloop:- user1- user2

5. 错误处理

- name: Ignore Failed Taskcommand: /bin/falseignore_errors: yes- name: Retry Taskshell: /opt/start_service.shretries: 3delay: 10

6. 注册变量 (`register`)

- name: Check Service Statuscommand: systemctl is-active nginxregister: service_status- name: Debug Statusdebug:var: service_status.stdout

四、模块化与复用

1. Include 与 Import

方法	说明
`import_playbook`	导入另一个 Playbook（静态，预处理阶段解析）
`import_tasks`	导入任务文件（静态）
`include_tasks`	动态包含任务文件（根据条件或循环动态加载）

示例：

- name: Include Common Tasksimport_tasks: common_tasks.yml

2. Roles 结构

roles/webserver/tasks/         # 主任务文件main.ymlhandlers/     # 处理器main.ymltemplates/    # Jinja2 模板nginx.conf.j2files/        # 静态文件index.htmlvars/         # 角色变量main.ymldefaults/    # 默认变量（优先级最低）main.ymlmeta/        # 依赖声明main.yml

使用角色：

- name: Apply Web Server Rolehosts: web_serversroles:- webserver

五、高级功能

1. 加密敏感数据 (Vault)

# 加密文件
ansible-vault encrypt vars/secrets.yml# 运行 Playbook 时解密
ansible-playbook site.yml --ask-vault-pass

2. 动态 Inventory

# inventory.ini
[web_servers]
localhost ansible_connection=local[all:vars]
ansible_python_interpreter=/usr/bin/python3

3. 异步任务

- name: Long Running Taskcommand: /path/to/long_script.shasync: 3600    # 最大运行时间（秒）poll: 0        # 不等待结果register: async_result- name: Check Async Taskasync_status:jid: "{{ async_result.ansible_job_id }}"register: job_resultuntil: job_result.finishedretries: 30

六、调试与验证

1. 语法检查

ansible-playbook playbook.yml --syntax-check

2. 空运行 (Dry Run)

ansible-playbook playbook.yml --check

3. 详细日志

ansible-playbook playbook.yml -v       # -v 到 -vvvv（详细程度递增）

4. 标签执行

tasks:- name: Install Packagesapt: name=nginxtags: install- name: Copy Configcopy: src=nginx.conf dest=/etc/nginx/tags: config

ansible-playbook playbook.yml --tags "install,config"

七、最佳实践

命名清晰：为 Play 和 Task 使用有意义的名称。
模块优先：尽量使用 Ansible 内置模块而非原始 Shell 命令。
变量分离：敏感数据通过 Vault 加密，通用变量放在 group_vars/ 或 host_vars/。
幂等性：确保任务可重复执行且结果一致（如使用 state: present 而非 latest）。
版本控制：将 Playbook 和 Roles 纳入 Git 管理。

八、完整 Playbook 示例

---
- name: Configure Web Serverhosts: web_serversbecome: yesvars:http_port: 8080max_clients: 200vars_files:- vars/secrets.ymltasks:- name: Install Nginxapt:name: nginxstate: presenttags: install- name: Copy Nginx Configtemplate:src: templates/nginx.conf.j2dest: /etc/nginx/nginx.confnotify: Restart Nginxtags: config- name: Ensure Nginx Runningservice:name: nginxstate: startedenabled: yestags: servicehandlers:- name: Restart Nginxservice:name: nginxstate: restarted