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: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"。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 # ... 更多数据库配置任务 ...
-