Ansible之Playbook（二）：模块大全

Ansible Playbook 模块大全

一、基础信息与连接性

setup:
- 说明 : 这是 Ansible 的"事实收集"模块。它在目标主机上自动运行（通常作为 Playbook 的第一个任务），收集关于该主机的各种信息（如 IP 地址、主机名、操作系统版本、磁盘、内存等），并将这些信息存储在 ansible_facts 变量中。
- 用途: 用于条件判断、动态配置（例如，根据实际内存大小调整配置）。
- 示例 :
  yaml 复制代码
```
- name: 收集目标主机信息
  setup:
```
- 后续任务可通过 {``{ ansible_facts['hostname'] }} 或 {``{ ansible_facts['distribution'] }} 等方式引用这些事实。
ping:
- 说明: 测试与目标主机的连接性和 Ansible 执行环境是否正常。它不发送 ICMP ping 包，而是检查 Python 环境是否可用。
- 用途: 快速检查主机是否可达且准备好执行任务。
- 示例 :
  yaml 复制代码
```
- name: 测试主机连接性
  ping:
```

二、系统配置与管理

hostname:
- 说明: 设置或修改目标主机的主机名。
- 常用参数 :
  - name: 要设置的新主机名。
- 示例 :
  yaml 复制代码
```
- name: 设置主机名为 server01
  hostname:
    name: server01
```
user:
- 说明: 管理用户账户（创建、修改、删除）。
- 常用参数 :
  - name: 用户名 (必填)。
  - state: present (创建/确保存在), absent (删除)。
  - password: 设置用户密码 (通常使用哈希值 {``{ 'mypassword' | password_hash('sha512') }})。
  - groups: 用户所属的主组或附加组列表。
  - shell: 用户的登录 shell (如 /bin/bash)。
  - home: 用户家目录路径。
  - uid: 用户 UID。
  - comment: 用户描述信息 (如全名)。
- 示例 :
  yaml 复制代码
```
- name: 创建用户 devuser 并设置密码
  user:
    name: devuser
    password: "{{ 'securepass' | password_hash('sha512') }}"
    shell: /bin/bash
    groups: wheel
    state: present
```
group:
- 说明: 管理用户组（创建、修改、删除）。
- 常用参数 :
  - name: 组名 (必填)。
  - state: present (创建/确保存在), absent (删除)。
  - gid: 组 GID。
- 示例 :
  yaml 复制代码
```
- name: 创建组 developers
  group:
    name: developers
    gid: 2000
    state: present
```

三、文件与目录管理

file:
- 说明: 管理文件、目录、符号链接的属性（状态、权限、所有权等）。
- 常用参数 :
  - path: 文件/目录/链接的路径 (必填)。
  - state: file (确保文件存在, 默认), directory (创建目录), link (创建符号链接), hard (创建硬链接), touch (创建空文件或更新时间戳), absent (删除)。
  - owner: 文件所有者。
  - group: 文件所属组。
  - mode: 文件权限 (八进制如 0644 或符号表示如 u=rw,g=r,o=r)。
  - src: 当 state=link 或 hard 时，源文件路径。
  - dest: 当 state=link 或 hard 时，目标链接路径 (通常等同于 path)。当 state=directory 时，创建目录的路径。
- 示例 :
  yaml 复制代码
```
- name: 确保目录 /data/logs 存在，权限 755，属于 appuser
  file:
    path: /data/logs
    state: directory
    owner: appuser
    group: appuser
    mode: '0755'

- name: 创建指向 /opt/app/config.conf 的符号链接 /etc/app.conf
  file:
    src: /opt/app/config.conf
    dest: /etc/app.conf
    state: link

- name: 删除临时文件 /tmp/oldfile
  file:
    path: /tmp/oldfile
    state: absent
```
lineinfile:
- 说明: 确保文件中存在特定的某一行，或者使用正则表达式匹配并替换/删除某一行。适用于单行修改。
- 常用参数 :
  - path: 目标文件路径 (必填)。
  - state: present (确保行存在), absent (确保行不存在)。
  - regexp: 用于匹配目标行的正则表达式 (当 state=present 且需要替换时，或 state=absent 时必填)。
  - line: 要插入或替换为的行内容 (当 state=present 时必填)。如果 regexp 匹配到，则替换匹配行；否则插入到文件末尾（或由 insertafter/insertbefore 指定位置）。
  - insertafter: 在匹配该正则表达式的行之后插入新行 (如果 regexp 未匹配或未提供时)。值可以是 EOF (文件末尾) 或正则表达式。
  - insertbefore: 在匹配该正则表达式的行之前插入新行。
  - backrefs: yes 时，如果 regexp 使用了捕获组 ()，则 line 中可以用 \1, \2 等引用它们。这常用于只修改匹配行的一部分。
  - create: 如果文件不存在，是否创建它。
- 示例 :
  yaml 复制代码
```
- name: 确保 /etc/ssh/sshd_config 包含 'PermitRootLogin no'
  lineinfile:
    path: /etc/ssh/sshd_config
    regexp: '^PermitRootLogin'
    line: 'PermitRootLogin no'
    state: present

- name: 注释掉 /etc/fstab 中关于 /dev/sdb1 的挂载行
  lineinfile:
    path: /etc/fstab
    regexp: '^[^#].*/dev/sdb1'
    line: '#\g<0>'  # 注释匹配的整行
    backrefs: yes

- name: 在文件末尾追加一行服务器地址
  lineinfile:
    path: /etc/hosts
    line: '192.168.1.100 myserver'
    state: present
    insertafter: EOF
```
blockinfile:
- 说明: 在文件中插入、替换或删除由唯一标记行包围的文本块。适用于管理配置文件中的多行配置段。
- 常用参数 :
  - path: 目标文件路径 (必填)。
  - block: 要插入的文本块内容 (多行字符串)。
  - state: present (确保块存在), absent (确保块不存在)。
  - marker: 定义包围块的开始和结束标记行。默认是 # BEGIN ANSIBLE MANAGED BLOCK 和 # END ANSIBLE MANAGED BLOCK。可以自定义，例如 marker: ""。
  - insertafter: 在匹配该正则表达式的行之后插入块 (如果文件中原无此标记块)。
  - insertbefore: 在匹配该正则表达式的行之前插入块。
  - create: 如果文件不存在，是否创建它。
- 示例 :
  yaml 复制代码
```
- name: 在 nginx.conf 中插入一个 server 块配置
  blockinfile:
    path: /etc/nginx/nginx.conf
    block: |
      server {
          listen 80;
          server_name example.com;
          root /var/www/html;
          index index.html;
      }
    marker: "# {mark} ANSIBLE MANAGED BLOCK - NGINX SERVER"
    insertafter: '^http {'
```
fetch:
- 说明: 从目标主机抓取文件到控制机（Ansible 运行的主机）。
- 常用参数 :
  - src: 目标主机上的文件路径 (必填)。
  - dest: 控制机上存放文件的目录路径。文件会按 主机名/文件路径 的结构保存。
  - flat: yes 时，不创建主机名目录，直接将文件保存到 dest 指定的路径（需确保文件名唯一）。
- 示例 :
  yaml 复制代码
```
- name: 抓取目标主机的 /var/log/messages 文件到控制机的 /tmp/logs/
  fetch:
    src: /var/log/messages
    dest: /tmp/logs/
```
copy:
- 说明: 将控制机上的文件或目录复制到目标主机。适合静态文件。
- 常用参数 :
  - src: 控制机上的文件或目录路径。
  - dest: 目标主机上的路径 (必填)。
  - owner: 目标文件所有者。
  - group: 目标文件所属组。
  - mode: 目标文件权限。
  - backup: yes 时，在覆盖前备份原文件。
  - force: yes (默认) 总是覆盖，no 仅当源文件不同时覆盖。
- 示例 :
  yaml 复制代码
```
- name: 复制本地配置文件到目标主机的 /etc/myapp/
  copy:
    src: files/myapp.conf
    dest: /etc/myapp/myapp.conf
    owner: root
    group: root
    mode: '0644'
```
template:
- 说明 : 使用 Jinja2 模板引擎，将控制机上的模板文件渲染后复制到目标主机。模板文件通常以 .j2 结尾。适合需要根据变量动态生成内容的文件。
- 常用参数 :
  - src: 控制机上的模板文件路径 (必填)。
  - dest: 目标主机上的路径 (必填)。
  - owner, group, mode, backup: 同 copy 模块。
- 示例 :
  yaml 复制代码
```
- name: 生成 nginx 配置文件
  template:
    src: templates/nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
```
  - nginx.conf.j2 示例内容:
    复制代码
```
server {
    listen {{ nginx_port }};
    server_name {{ server_name }};
    ...
}
```
archive:
- 说明 : 在目标主机上将文件或目录打包压缩成归档文件（如 .tar.gz, .zip）。
- 常用参数 :
  - path: 要归档的文件或目录路径 (必填)。
  - dest: 生成的归档文件在目标主机上的路径 (必填)。
  - format: 归档格式 (zip, gztar/tar.gz, bztar/tar.bz2, xztar/tar.xz)。
- 示例 :
  yaml 复制代码
```
- name: 将 /var/log 打包成 logs.tar.gz 存放到 /backups
  archive:
    path: /var/log
    dest: /backups/logs.tar.gz
    format: gztar
```
unarchive:
- 说明: 解压缩归档文件到目标主机上的指定路径。支持本地文件复制解压或从 URL 下载解压。
- 常用参数 :
  - src: 归档文件路径。可以是控制机路径 (复制到目标机后解压)，目标机路径，或 URL (下载后解压)。
  - dest: 解压的目标目录路径 (必填)。
  - remote_src: yes 表示 src 在目标主机上；no (默认) 表示 src 在控制机上。
  - creates: 如果指定路径已存在，则跳过解压。可用于幂等性。
- 示例 :
  yaml 复制代码
```
- name: 解压控制机上的软件包到目标主机的 /opt
  unarchive:
    src: files/myapp.tar.gz
    dest: /opt
    remote_src: no

- name: 下载并解压软件包 (remote_src 隐含为 yes)
  unarchive:
    src: https://example.com/releases/app-v1.0.tar.gz
    dest: /opt/app
```

四、软件包管理 (OpenEuler 使用 DNF)

yum / dnf:
- 说明 : 在基于 Red Hat 的系统 (如 CentOS, RHEL, Fedora, OpenEuler) 上管理软件包。在 OpenEuler 上，底层使用的是 dnf，但 Ansible 的 yum 模块兼容调用 dnf。
- 常用参数 :
  - name: 软件包名称 (必填)。可以是单个包名、逗号分隔的列表，或带有版本的 package-1.0，或 URL。
  - state: present (安装，默认), latest (升级到最新), absent (卸载)。
  - enablerepo: 临时启用指定的仓库 ID。
  - disablerepo: 临时禁用指定的仓库 ID。
  - update_cache: yes 在执行操作前更新仓库缓存（相当于 dnf makecache）。
- 示例 :
  yaml 复制代码
```
- name: 安装 nginx
  yum:  # 在 OpenEuler 上实际调用 dnf
    name: nginx
    state: present

- name: 安装多个开发工具
  yum:
    name:
      - git
      - gcc
      - make
    state: present

- name: 卸载旧版本的 app
  yum:
    name: old-app
    state: absent

- name: 更新所有软件包到最新版本
  yum:
    name: '*'
    state: latest
```
package:
- 说明 : 这是一个通用包管理模块。Ansible 会根据目标系统的包管理器（yum, apt, dnf, zypper, pacman 等）自动选择合适的底层模块。建议优先使用特定模块（如 yum）以获得更精确的控制。
- 常用参数 : 同 yum (name, state 等)。
- 示例 :
  yaml 复制代码
```
- name: 使用通用模块安装 vim (系统自动选择 yum/dnf)
  package:
    name: vim-enhanced
    state: present
```
package_facts:
- 说明 : 收集目标主机上已安装软件包的信息，并将其存储在 ansible_facts.packages 字典中。
- 用途: 用于检查特定软件包是否安装，或根据已安装包做条件判断。
- 示例 :
  yaml 复制代码
```
- name: 收集已安装的软件包信息
  package_facts:

- name: 检查是否安装了 nginx
  debug:
    msg: "Nginx is installed"
  when: "'nginx' in ansible_facts.packages"
```
yum_repository:
- 说明: 管理目标主机上的 YUM/DNF 软件仓库配置。
- 常用参数 :
  - name: 仓库 ID (必填，如 epel)。
  - state: present (添加/确保仓库存在), absent (删除仓库)。
  - description: 仓库描述。
  - baseurl: 仓库的基础 URL。
  - gpgcheck: yes (默认) 启用 GPG 检查, no 禁用。
  - gpgkey: GPG 密钥 URL。
  - enabled: yes (默认) 启用仓库, no 禁用。
- 示例 :
  yaml 复制代码
```
- name: 添加 EPEL 仓库
  yum_repository:
    name: epel
    description: EPEL YUM repo
    baseurl: https://mirrors.aliyun.com/epel/$releasever/$basearch/
    gpgkey: https://mirrors.aliyun.com/epel/RPM-GPG-KEY-EPEL-$releasever
    gpgcheck: yes
    enabled: yes
```

五、磁盘与文件系统管理

filesystem:
- 说明: 在目标主机上的块设备（磁盘分区）上创建文件系统（格式化）。
- 常用参数 :
  - dev: 目标块设备路径 (如 /dev/sdb1) (必填)。
  - fstype: 要创建的文件系统类型 (如 ext4, xfs, btrfs, vfat) (必填)。
  - force: yes 强制格式化（即使设备已有文件系统或正在使用）。
- 示例 :
  yaml 复制代码
```
- name: 在 /dev/vdb1 上创建 XFS 文件系统
  filesystem:
    dev: /dev/vdb1
    fstype: xfs
```
lvol / lvg:
- 说明 : 管理 LVM（逻辑卷管理）。通常分两步：
  - lvg：管理卷组 (Volume Group)。
  - lvol：管理逻辑卷 (Logical Volume)。
- lvg 常用参数 :
  - vg: 卷组名称 (必填)。
  - pvs: 组成卷组的物理卷 (Physical Volumes) 列表 (如 ["/dev/sdb", "/dev/sdc"]) (必填)。
  - state: present (创建/确保存在), absent (删除卷组，需先移除所有逻辑卷)。
- lvol 常用参数 :
  - lv: 逻辑卷名称 (必填)。
  - vg: 逻辑卷所属的卷组名称 (必填)。
  - size: 逻辑卷大小。支持 10G, 512M 等格式，或 +100%FREE 使用剩余空间。
  - state: present (创建/确保存在), absent (删除逻辑卷)。
- 示例 :
  yaml 复制代码
```
- name: 在 /dev/vdb 和 /dev/vdc 上创建卷组 datavg
  lvg:
    vg: datavg
    pvs:
      - /dev/vdb
      - /dev/vdc
    state: present

- name: 在 datavg 上创建大小为 20G 的逻辑卷 datalv
  lvol:
    lv: datalv
    vg: datavg
    size: 20G
    state: present
```
mount:
- 说明 : 挂载或卸载文件系统，或管理 /etc/fstab 中的永久挂载项。
- 常用参数 :
  - path: 挂载点路径 (必填)。
  - src: 要挂载的设备 (如 /dev/sdb1) 或远程资源 (如 nfs-server:/export)。对于 tmpfs，是 tmpfs。
  - fstype: 文件系统类型 (如 ext4, xfs, nfs, tmpfs)。
  - state: mounted (挂载并确保 /etc/fstab 有项), present (只确保 /etc/fstab 有项，不立即挂载), unmounted (卸载，但 /etc/fstab 项保留), absent (卸载并移除 /etc/fstab 项)。
  - opts: 挂载选项 (如 defaults, ro, rw,noatime)。
- 示例 :
  yaml 复制代码
```
- name: 挂载 /dev/datavg/datalv 到 /data 并写入 fstab
  mount:
    path: /data
    src: /dev/datavg/datalv
    fstype: xfs
    opts: defaults
    state: mounted

- name: 卸载 /mnt/tmp
  mount:
    path: /mnt/tmp
    state: unmounted
```

六、服务与任务管理

service:
- 说明: 管理系统服务（守护进程）的状态（启动、停止、重启、重载、启用开机启动等）。
- 常用参数 :
  - name: 服务名称 (必填)。
  - state: started (启动服务), stopped (停止服务), restarted (重启服务), reloaded (重载配置)。
  - enabled: yes (启用开机启动), no (禁用开机启动)。
- 示例 :
  yaml 复制代码
```
- name: 确保 nginx 服务正在运行并启用开机启动
  service:
    name: nginx
    state: started
    enabled: yes

- name: 重启 sshd 服务以应用新配置
  service:
    name: sshd
    state: restarted
```
cron:
- 说明: 管理周期性任务（Cron Jobs）。
- 常用参数 :
  - name: Cron 作业的描述性名称 (必填，用于标识任务)。
  - job: 要执行的命令 (必填)。
  - minute, hour, day, month, weekday: 时间字段 (默认是 *)。支持标准 cron 语法 (*, */5, 1,3, 1-5 等)。
  - user: 以哪个用户的身份执行任务 (默认是 root)。
  - state: present (添加/确保存在), absent (删除)。
  - disabled: yes 时注释掉该 cron 作业（相当于禁用），state 仍需为 present。
- 示例 :
  yaml 复制代码
```
- name: 添加每天凌晨 3 点运行的备份脚本
  cron:
    name: "Daily Backup"
    job: "/opt/scripts/backup.sh"
    minute: "0"
    hour: "3"
    user: backupuser

- name: 删除名为 'Old Cleanup' 的 cron 作业
  cron:
    name: "Old Cleanup"
    state: absent
```
reboot:
- 说明: 重启目标主机。通常用于内核升级后或重大配置变更后。
- 常用参数 :
  - reboot_timeout: 等待系统重新上线的最长时间（秒），默认 600。
  - connect_timeout: 重启后等待初始连接的时间（秒），默认 60。
  - msg: 重启前显示给用户（如果可能）的消息。
  - pre_reboot_delay: 执行重启命令前等待的秒数（默认 0）。
  - post_reboot_delay: 系统启动后等待的秒数（默认 0）。
- 注意 : 使用此模块时，Playbook 的执行会暂停等待主机重启并重新连接。确保 Playbook 有处理重启的策略（如使用 serial: 1 逐台重启集群节点）。
- 示例 :
  yaml 复制代码
```
- name: 重启服务器 (例如内核升级后)
  reboot:
    reboot_timeout: 1200
    msg: "System will reboot now for kernel update."
```

七、网络与防火墙

firewalld:
- 说明 : 管理 firewalld 防火墙（OpenEuler 默认使用）。
- 常用参数 :
  - service: 要允许的服务名称 (如 http, ssh, https)。与 port 互斥。
  - port: 要允许的端口/协议 (如 80/tcp, 443/tcp)。与 service 互斥。
  - zone: 目标区域 (如 public, dmz, trusted)。默认通常是 public。
  - state: enabled (永久添加规则), disabled (永久移除规则)。immediate 参数控制是否立即生效。
  - permanent: yes (默认) 规则写入持久配置，重启后有效；no 仅临时生效。
  - immediate: yes 时立即应用更改（即使 permanent=yes 也需要这个来立即生效）。
- 示例 :
  yaml 复制代码
```
- name: 永久允许 http 服务在 public 区域
  firewalld:
    service: http
    zone: public
    state: enabled
    permanent: yes
    immediate: yes

- name: 临时允许 8080/tcp 端口
  firewalld:
    port: 8080/tcp
    state: enabled
    permanent: no
    immediate: yes  # immediate 在 permanent=no 时是必须的
```
get_url:
- 说明: 从 URL 下载文件到目标主机。
- 常用参数 :
  - url: 要下载的 URL (必填)。
  - dest: 文件在目标主机上的保存路径 (必填)。
  - mode: 文件权限。
  - checksum: 文件的预期校验和 (如 sha256:abcd... 或 sha256:{``{ lookup('file', 'local/path/file.sha256') }}) 用于验证下载完整性。
  - timeout: 下载超时时间 (秒)。
- 示例 :
  yaml 复制代码
```
- name: 下载 OpenJDK 安装包
  get_url:
    url: https://example.com/releases/openjdk-11.tar.gz
    dest: /opt/openjdk-11.tar.gz
    checksum: sha256:b7c4d6e6b98b6d8c6e2d...
```

八、脚本与命令执行

command:
- 说明 : 在目标主机上执行命令。命令通过 shell 执行，但不通过 /bin/sh 处理管道、重定向等（直接调用可执行文件）。不支持管道 |、重定向 > <、环境变量 VAR=value 等 shell 特性。
- 常用参数 :
  - cmd: 要执行的命令和参数 (必填)。
  - creates: 如果该路径的文件/目录已存在，则跳过此命令。
  - removes: 如果该路径的文件/目录不存在，则跳过此命令。
  - chdir: 执行命令前切换到的目录。
- 示例 :
  yaml 复制代码
```
- name: 运行初始化脚本 (无 shell 特性)
  command: /opt/scripts/init.sh --verbose
  args:
    chdir: /tmp

- name: 编译程序 (如果尚未编译)
  command: make
  args:
    chdir: /src/myapp
    creates: /src/myapp/myapp
```
shell:
- 说明 : 在目标主机上通过 shell (默认 /bin/sh) 执行命令。支持管道、重定向、环境变量等 shell 特性。
- 常用参数 : 同 command (cmd, creates, removes, chdir)。
- 警告 : 使用 shell 模块比 command 更灵活但可能更不安全（涉及 shell 注入风险）。如果命令不需要 shell 特性，优先使用 command。
- 示例 :
  yaml 复制代码
```
- name: 统计进程数量
  shell: ps aux | grep nginx | grep -v grep | wc -l
  register: process_count

- name: 使用环境变量执行
  shell: |
    export PATH=$PATH:/opt/bin
    some_command
  args:
    chdir: /home/user
```
script:
- 说明: 将控制机上的脚本文件传输到目标主机并执行它。
- 常用参数 :
  - cmd: 脚本文件在控制机上的路径 (必填)。
  - creates, removes: 同 command/shell。
- 示例 :
  yaml 复制代码
```
- name: 在目标主机上运行本地部署脚本
  script: scripts/deploy_app.sh
  args:
    chdir: /tmp
```

九、Kubernetes 管理 (高级)

k8s :
- 说明 : 管理 Kubernetes 资源（Deployment, Service, ConfigMap, Secret, Namespace 等）。需要目标主机上有 kubectl 且配置好 kubeconfig，或者 Playbook 在能访问集群的控制机上运行。
- 常用参数 :
  - definition: YAML/JSON 格式的 Kubernetes 资源定义内容 (内嵌字符串)。
  - src: Kubernetes 资源定义文件的路径（本地文件）。
  - state: present (创建/更新), absent (删除)。
  - namespace: 资源所属的命名空间。
  - kubeconfig: kubeconfig 文件路径。
  - context: kubeconfig 中的上下文名称。
- 示例 :
  yaml 复制代码
```
- name: 从 YAML 文件创建 Deployment
  k8s:
    src: manifests/nginx-deployment.yaml
    state: present
```

十、综合示例 (`main.yml`)

main.yml (示例结构) :

这不是一个模块，而是 Playbook 的主要入口文件。它通常包含多个 play，每个 play 针对一组主机执行一系列 task（使用上述模块）。

示例结构 :

yaml 复制代码

---
- name: 配置 Web 服务器组
  hosts: webservers  # 主机组名，在 inventory 中定义
  become: yes        # 以 sudo 权限执行
  tasks:
    - name: 安装依赖
      yum:
        name:
          - nginx
          - php-fpm
        state: present

    - name: 配置 nginx
      template:
        src: templates/nginx.conf.j2
        dest: /etc/nginx/nginx.conf
        owner: root
        group: root
        mode: '0644'
      notify: Restart nginx  # 触发 handler

    - name: 部署应用代码
      copy:
        src: ../webapp/
        dest: /var/www/html/
        owner: apache
        group: apache

    - name: 确保 nginx 运行并开机启动
      service:
        name: nginx
        state: started
        enabled: yes

  handlers:
    - name: Restart nginx
      service:
        name: nginx
        state: restarted

- name: 配置数据库服务器
  hosts: dbservers
  become: yes
  tasks:
    - name: 安装 MariaDB
      yum:
        name: mariadb-server
        state: present
    # ... 更多数据库配置任务 ...

Ansible之Playbook（二）：模块大全

Ansible Playbook 模块大全

一、基础信息与连接性

二、系统配置与管理

三、文件与目录管理

四、软件包管理 (OpenEuler 使用 DNF)

五、磁盘与文件系统管理

六、服务与任务管理

七、网络与防火墙

八、脚本与命令执行

九、Kubernetes 管理 (高级)

十、综合示例 (main.yml)

十、综合示例 (`main.yml`)