基础设施即代码 / 知识点
Ansible 常用模块速查
连接与执行
ansible <host-pattern> -m ansible.builtin.ping检查 Ansible 是否能连接目标主机并完成模块执行;不等同于网络层 ping,适合首次接入、凭据验证和故障排查。
测试主机连通性
首次接入主机、修改 SSH 凭据或排查执行失败时,用 ansible.builtin.ping 验证从控制节点到目标主机的连接、认证以及 Python 模块执行链路是否正常。它不是 ICMP ping;返回 pong 表示 Ansible 已成功执行模块。
基本语法
ansible <host-pattern> -m ansible.builtin.ping<host-pattern> 指定 Inventory 中的目标主机或主机组。常见的 all 会匹配当前 Inventory 中的全部主机;需要指定 Inventory 文件时可增加 -i <PATH>。
连通性验证
ansible all -m ansible.builtin.ping预期输出:成功主机通常显示 SUCCESS,并返回 pong;主机名及其他执行元数据可能因环境和 Ansible 版本不同而变化。
<HOST> | SUCCESS => {
"changed": false,
"ping": "pong"
}如果需要先确认目标是否被 Inventory 正确匹配,可执行:
ansible all --list-hosts预期结果:输出匹配到的主机数量和主机列表;若数量为 0,应先检查 Inventory 和 host pattern,而不是继续排查远端连接。
失败时怎么看
UNREACHABLE 通常表示连接或认证阶段没有完成,应检查目标地址、SSH 端口、用户、密钥和网络可达性。模块执行阶段报错则还要检查远端运行 Ansible 模块所需的环境,例如可用的 Python 解释器。
风险与边界
该模块主要用于连接与执行能力验证,不用于判断业务端口、HTTP 服务或数据库是否健康。排障时先用 --list-hosts 确认目标范围,再执行 ping 模块,可以避免把 Inventory 匹配错误误判为远端故障。
ansible <host-pattern> -m ansible.builtin.command -a '<command>'直接执行不经过 shell 解析的外部命令;适合简单可预测的命令调用,不支持管道、重定向和 shell 变量展开。
执行简单命令
需要在目标主机直接运行一个外部程序,又不需要管道、重定向、通配符或 shell 变量展开时使用 ansible.builtin.command。它绕过 shell 解释,更适合参数明确、行为可预测的命令。
基本语法
ansible <host-pattern> -m ansible.builtin.command -a '<command>'<host-pattern> 决定执行范围,-m 指定 ansible.builtin.command,-a 后传入要执行的程序及参数。命令由目标主机执行,因此对应的可执行文件必须存在于远端环境。
常用示例
查看所有匹配主机的内核版本:
ansible all -m ansible.builtin.command -a 'uname -r'预期输出:每台成功执行的主机会显示 CHANGED 或相应成功状态,并在标准输出中给出该主机实际的内核版本;版本值因目标系统而异。
<HOST> | CHANGED | rc=0 >>
<KERNEL_VERSION>其中 <HOST> 和 <KERNEL_VERSION> 是动态值。rc=0 表示命令正常退出;排障时还应读取标准输出或错误输出判断程序本身的执行结果。
不经过 shell
command 不会把命令交给 shell 解析,因此不要直接写依赖 |、>、&&、环境变量展开等 shell 语法的命令。例如下面的写法不能按 shell 管道的含义执行:
ansible all -m ansible.builtin.command -a 'printf hello | wc -c'预期结果:| 不会被当作 shell 管道处理,命令不会得到预期的管道计算结果。确实依赖 shell 语法时应改用专门支持 shell 解析的模块,并同时评估引用和输入注入风险。
幂等性与风险
command 只负责调用命令,本身不能保证该命令幂等。查询类命令通常风险较低,但如果执行创建、删除、重启或修改数据的程序,重复运行可能产生重复副作用。
ansible <host-pattern> -m ansible.builtin.shell -a '<command>'通过远端 shell 执行命令,可使用管道、重定向和变量;适合已有脚本逻辑但应优先评估是否能改成幂等模块。
执行 Shell 命令
需要在远端使用管道、重定向、变量展开等 shell 能力时使用 ansible.builtin.shell。它适合执行现成 shell 逻辑,但命令是否幂等由调用者负责;如果已有专用 Ansible 模块能完成同一任务,通常应优先使用专用模块。
基本语法
ansible <host-pattern> -m ansible.builtin.shell -a '<command>'<host-pattern> 是 inventory 中的主机或主机组模式,<command> 交给远端 shell 解释,因此可以包含 |、>、&& 等 shell 运算符。控制节点仍需能够通过 inventory 和连接配置访问目标主机。
常用示例
查看目标主机的文件系统容量,并通过管道跳过 df 的标题行:
ansible all -m ansible.builtin.shell -a 'df -h | tail -n +2'预期输出:每台成功执行的主机会返回 SUCCESS 和文件系统容量信息;设备名、容量、挂载点等内容取决于目标主机。例如输出形态可能为:
<HOST> | CHANGED | rc=0 >>
<FILESYSTEM> <SIZE> <USED> <AVAIL> <USE%> <MOUNTPOINT><HOST>、文件系统名称和容量等均为动态值。这里出现 CHANGED 不代表磁盘状态被修改,而是 ad-hoc shell 执行通常不能仅凭任意命令判断是否改变了远端状态。
与 command 的边界
如果命令只是运行一个程序并传递参数,不依赖管道、重定向、变量展开等 shell 语法,应优先考虑 ansible.builtin.command。使用 shell 会增加引号、变量展开以及输入拼接带来的风险。
风险与恢复
shell 本身没有通用回滚能力:命令造成的文件删除、覆盖或服务变更,需要由对应系统操作恢复。执行有副作用的命令前,可先用 --limit 缩小目标范围,或改用能够表达期望状态并提供幂等性的专用模块。
ansible <host-pattern> -m ansible.builtin.raw -a '<command>'在远端直接执行命令,不依赖目标机上的 Python;适合 bootstrap 场景或 Python 不可用时的最低层接入。
执行原始命令
目标机尚未具备可供常规模块使用的 Python 环境,或需要在 bootstrap 阶段先执行最低层命令时,可使用 ansible.builtin.raw。它把命令直接交给远端执行,不经过通常的模块子系统,因此适合初始化,而不是日常配置管理的默认选择。
基本语法
ansible <host-pattern> -m ansible.builtin.raw -a '<command>'<host-pattern> 指定 inventory 中的执行目标,<command> 是发送到远端执行的命令。即使不依赖目标机 Python,Ansible 仍需要已有可用的远程连接方式和相应权限。
常用示例
先用一个只读命令确认最低层远程执行链路可用:
ansible all -m ansible.builtin.raw -a 'uname -s'预期输出:类 Unix 目标机成功执行时会返回 SUCCESS,并显示 uname -s 的标准输出。例如 Linux 主机通常可见:
<HOST> | SUCCESS | rc=0 >>
Linux<HOST> 是实际 inventory 主机名;其他操作系统的输出可能不同。若连接、认证或远端命令本身失败,应根据返回的连接错误或非零 rc 继续定位,而不是把问题归因于 Python 模块环境。
适用边界
raw 的典型用途是引导一台尚未满足常规模块运行条件的主机,例如先准备基础运行环境。目标机条件满足后,应尽快切换到对应的专用模块,以获得更明确的参数模型、状态判断和幂等行为。
raw 不提供任意命令的通用幂等保证,也不会自动理解命令造成了什么系统状态变化。重复执行安装、覆盖或删除类命令前,需要自行判断其重复执行后果。
风险与恢复
raw 没有统一回滚机制。只读探测命令通常无需恢复;若用于安装软件、修改配置或删除文件,恢复方式取决于实际执行的命令。完成 bootstrap 后,用常规模块验证并管理最终状态,避免长期依赖不可声明状态的原始命令。
文件与配置
ansible <host-pattern> -m ansible.builtin.copy -a 'src=<src> dest=<dest>'将控制节点文件复制到目标主机并可同步权限、属主和模式;适合部署静态配置、小型脚本和证书等文件。
复制文件到主机
需要把控制节点上的静态文件分发到目标主机时使用 ansible.builtin.copy。模块会比较目标状态,只在需要时写入文件;还可同时设置权限、属主和属组。
基本语法
ansible <host-pattern> -m ansible.builtin.copy -a 'src=<src> dest=<dest>'src 默认指控制节点上的源文件或目录,dest 是目标主机上的目标路径。常用的 mode 设置权限,owner 和 group 分别设置属主与属组。
常用示例
先确保当前目录存在 app.conf,并且 inventory 中的 all 能匹配目标主机,然后执行:
ansible all -m ansible.builtin.copy -a 'src=./app.conf dest=/tmp/app.conf mode=0644'预期结果:成功的目标主机返回 SUCCESS;首次复制或内容、权限发生变化时结果中的 changed 为 true,目标已经符合要求时通常为 false。具体输出还会包含模块返回的文件属性等信息。
可继续验证目标文件:
ansible all -m ansible.builtin.command -a 'ls -l /tmp/app.conf'预期结果:命令成功,并能看到 /tmp/app.conf;权限应对应 0644。属主、属组取决于目标主机上的实际执行用户及既有文件状态。
风险与恢复
如果 dest 已存在且内容不同,copy 会用源文件内容更新它;部署关键配置前应确认目标路径,必要时使用模块支持的备份能力保留旧版本。写入 /etc 等受保护目录还需要目标账户具备权限,通常通过 Ansible 的权限提升机制执行。
ansible <host-pattern> -m ansible.builtin.template -a 'src=<src> dest=<dest>'使用 Jinja2 将变量渲染成目标文件;适合环境差异明显的服务配置,模板内容变化时模块会自动判断是否需要更新。
渲染配置模板
同一份配置需要根据主机变量、组变量或事实生成不同内容时使用 ansible.builtin.template。它在控制端用 Jinja2 渲染模板,再把结果写入目标主机,并根据最终状态判断是否需要更新文件。
基本语法
ansible <host-pattern> -m ansible.builtin.template -a 'src=<src> dest=<dest>'src 是控制节点上的 Jinja2 模板,dest 是目标主机上的输出路径。模板中可以引用当前 Ansible 上下文可用的变量;如果引用未定义变量,任务通常会失败,而不是静默生成空值。
渲染示例
假设当前目录已有 nginx.conf.j2,且其中使用的变量均已定义,可以执行:
ansible all -m ansible.builtin.template -a 'src=./nginx.conf.j2 dest=/etc/nginx/nginx.conf'预期结果:有写入权限且模板能正常渲染时,目标主机返回 SUCCESS。渲染结果与现有文件不同时,结果中的 changed 为 true;内容已经一致时通常为 false。
随后检查文件是否已经落盘:
ansible all -m ansible.builtin.command -a 'test -s /etc/nginx/nginx.conf'预期结果:目标文件存在且非空时命令成功,返回码为 0。这只能验证文件存在且有内容;是否为有效的 Nginx 配置,还应在目标环境使用对应服务自身的配置检查命令验证。
风险与恢复
模板渲染成功不等于服务配置一定有效。生产环境更新关键配置时,应先保证变量完整,并结合服务自身的语法检查;目标路径已有文件时,还应根据变更风险决定是否启用模块支持的备份能力。
ansible <host-pattern> -m ansible.builtin.file -a 'path=<path> state=<state>'统一处理文件、目录、软链接及权限属性;适合创建目录、删除路径、建立链接和修正属主模式等常见配置动作。
管理文件状态
需要批量创建目录、删除路径、建立软链接,或统一文件属主和权限时使用 ansible.builtin.file。模块按声明的目标状态执行,目标已经符合要求时通常不会重复产生变更。
基本语法
ansible <host-pattern> -m ansible.builtin.file -a 'path=<path> state=<state>'path 指定远程主机上的目标路径,state 决定期望状态。常用状态包括 directory、file、touch、link、hard 和 absent;其中 file 不会在路径不存在时创建普通文件,需要创建空文件可使用 touch。
关键选项
state=directory:确保目录存在,缺失时创建目录。state=absent:确保目标不存在,可删除文件、软链接或目录;删除目录时会连同其内容一起移除。state=link:创建或维护软链接,并通过src指定链接目标。owner、group:设置属主和属组,目标主机上需要存在对应用户或组。mode:设置权限模式。通过 ad-hoc 命令传递时可使用0755这类形式,并保持在参数字符串中。recurse=yes:对目录中的现有内容递归应用指定的文件属性,影响范围可能很大,应谨慎使用。
创建目录并验证
下面确保所有匹配主机上的 /opt/app 是目录且权限为 0755,随后使用 stat 查看结果。
ansible all -m ansible.builtin.file -a 'path=/opt/app state=directory mode=0755'
ansible all -m ansible.builtin.stat -a 'path=/opt/app'预期结果:第一次执行在目录不存在或属性不符时返回 changed=true;再次以相同参数执行通常返回 changed=false。验证结果的 stat.exists 应为 true、stat.isdir 应为 true,权限可读取 stat.mode,实际输出还会包含其他文件元数据。
风险与恢复
权限或属主设置错误时,可再次运行 ansible.builtin.file 声明正确的 mode、owner 和 group 进行修正。被 state=absent 删除的数据不能由该模块自动恢复,需要从备份或其他可靠副本恢复。
ansible <host-pattern> -m ansible.builtin.stat -a 'path=<path>'读取文件或目录的存在性、类型、权限和校验等元数据;适合在条件判断前做探测,不直接修改目标状态。
查看文件信息
需要在修改配置前确认远程路径是否存在、属于什么类型、权限如何,或读取文件校验信息时使用 ansible.builtin.stat。它只采集目标元数据,不负责创建、删除或修改文件。
基本语法
ansible <host-pattern> -m ansible.builtin.stat -a 'path=<path>'path 是要检查的远程路径。执行成功后,结果集中在 stat 对象中;实际可用字段与目标类型、模块参数及目标系统有关,因此判断前应先确认字段是否存在。
常用读取项
stat.exists:目标是否存在,是后续条件判断最常用的入口。stat.isdir:目标存在且为目录时用于识别目录。stat.isreg:目标存在且为普通文件时用于识别普通文件。stat.islnk:用于判断目标是否为符号链接。stat.mode:读取权限模式,常用于核对配置文件权限。stat.pw_name、stat.gr_name:在能够解析属主和属组名称时读取对应名称。stat.checksum:启用并能够计算校验和时用于比较文件内容;不要假定不存在的路径一定带有该字段。
查看文件并读取结果
下面检查 /etc/hosts,不会修改远程文件。
ansible all -m ansible.builtin.stat -a 'path=/etc/hosts'预期结果:对常见 Linux 主机上的现有 /etc/hosts,任务成功时输出包含 stat 对象,可从中读取 exists、文件类型、权限等字段。例如应重点检查 stat.exists 是否为 true;完整字段和具体值取决于目标主机,不应依赖输出字段顺序。
不存在路径的处理
路径不存在本身通常是一次成功的探测,而不是模块执行失败。此时应先读取 stat.exists,再决定是否执行创建、复制或其他修改动作。在 Playbook 中引用仅在目标存在时才有的属性时,也应先做存在性判断,避免把缺失字段当成固定值。
边界与排查
stat 是探测模块,不会替你修复权限或创建缺失文件;确认状态后,可再选择 ansible.builtin.file、ansible.builtin.copy 等模块声明目标状态。如果命令本身失败,应区分文件不存在与连接、权限、Python 环境等执行问题:前者通常体现在 stat.exists=false,后者则需要根据 Ansible 返回的失败信息继续排查。
ansible <host-pattern> -m ansible.builtin.lineinfile -a 'path=<path> regexp=<regexp> line=<line>'按正则定位并维护单行文本;适合 SSH、内核参数等简单键值配置,复杂多行结构应优先使用 template。
修改单行配置
需要确保配置文件中的某一行始终保持指定内容时使用 ansible.builtin.lineinfile。它会按正则查找目标行并替换为期望值;重复执行时,文件已经符合要求便不会再次修改。
基本语法
ansible <host-pattern> -m ansible.builtin.lineinfile -a 'path=<path> regexp=<regexp> line=<line>'path:远程主机上要维护的文件路径。regexp:用于定位已有行的 Python 正则表达式。应尽量限定到唯一配置项,避免匹配无关内容。line:目标行最终应具有的完整文本。
如果文件需要管理员权限,还需根据目标主机的权限配置使用 Ansible 的提权选项;这不属于模块参数本身。
常用示例
下面把 /tmp/app.conf 中以 port= 开头的配置维护为 port=8080。先创建可控的测试文件,再执行模块,因此可以安全验证替换行为。
ansible all -m ansible.builtin.copy -a 'dest=/tmp/app.conf content="port=8000\n"'
ansible all -m ansible.builtin.lineinfile -a 'path=/tmp/app.conf regexp="^port=" line="port=8080"'
ansible all -m ansible.builtin.command -a 'cat /tmp/app.conf'预期结果:首次执行 lineinfile 时目标主机的任务结果显示发生变更,最后一条命令读取到以下内容;再次执行同一 lineinfile 命令时应不再产生文件变更。
port=8080实际 Ansible 输出还会包含主机名、changed 等执行信息,其格式可能随 Ansible 版本和输出回调配置不同。
匹配边界
regexp 最好同时覆盖旧值和目标值。例如 ^port= 在修改前后都能定位同一个配置项,有利于保持幂等。如果正则没有匹配已有内容,lineinfile 的默认行为可能是在文件中加入目标行,而不是替换你原本想修改的行。
风险与恢复
生产环境可先限制到测试主机,并结合 Ansible 的检查模式观察是否会产生变更。若误改,应把 line 调整回确认过的旧值后再次执行,或使用已有备份恢复文件;不要在不知道原始值时猜测恢复内容。
ansible <host-pattern> -m ansible.builtin.replace -a 'path=<path> regexp=<regexp> replace=<replace>'在文件中按正则批量替换匹配内容;适合已有配置文件的局部调整,但要先确认正则范围避免误修改其他配置。
批量替换文本
需要在已有文件中把所有符合正则的文本统一替换时使用 ansible.builtin.replace。它适合已知格式的局部批量修改;关键是先收紧 regexp,因为匹配范围过大会同时改掉多个非目标位置。
基本语法
ansible <host-pattern> -m ansible.builtin.replace -a 'path=<path> regexp=<regexp> replace=<replace>'path:远程主机上待修改的文件。regexp:定位待替换内容的 Python 正则表达式。replace:用于替换每个匹配结果的文本。
模块会处理文件中的匹配项,而不是只维护某一条配置记录。只需要保证单个配置项存在且值正确时,ansible.builtin.lineinfile 通常更直接。
常用示例
下面先创建一个测试配置,再把所有以 port= 开头的整行替换为 port=8080,最后读取文件验证结果。
ansible all -m ansible.builtin.copy -a 'dest=/tmp/app.conf content="port=8000\nmode=prod\nport=9000\n"'
ansible all -m ansible.builtin.replace -a 'path=/tmp/app.conf regexp="^port=.*$" replace="port=8080"'
ansible all -m ansible.builtin.command -a 'cat /tmp/app.conf'预期结果:两个匹配行都会被替换,未匹配的 mode=prod 保持不变;再次执行相同替换时文件内容应保持一致。
port=8080
mode=prod
port=8080实际 Ansible 回显还会包含主机名、返回码和 changed 等信息,具体展示可能随版本及输出回调配置变化。
正则范围
replace 会作用于正则匹配到的所有目标,因此不要把 .* 等宽泛模式直接用于尚未检查结构的生产配置。锚定行首、配置键或其他稳定上下文,通常比只搜索一个短字符串更安全。
可在执行前先用与目标文件相匹配的文本检查工具验证正则思路,并把 Ansible 的实际变更范围限制到测试主机。正则是否跨行以及锚点的具体行为还取决于模块的正则处理规则,复杂多行修改应查对应 Ansible 版本的模块文档后再实施。
风险与恢复
发现误替换后,应使用已知正确的原始内容或备份恢复,再缩小 regexp 后重新执行。对于需要维护完整文件结构的配置,改用 ansible.builtin.template 通常比连续执行多次正则替换更容易审查和回滚。
ansible <host-pattern> -m ansible.builtin.blockinfile -a 'path=<path> block=<block>'以标记边界维护一整段文本内容;适合集中管理多行片段,同时避免手工追加导致重复配置和难以回滚。
维护多行配置块
需要由 Ansible 持续维护配置文件中的一整段文本时使用 ansible.builtin.blockinfile。模块会用标记包围受管内容,后续再次执行时更新该块,而不是不断追加重复内容。
基本语法
ansible <host-pattern> -m ansible.builtin.blockinfile -a 'path=<path> block=<block>'path 指定远程文件,block 是要维护的多行内容。默认情况下,模块会在受管块前后加入 Ansible 标记,以便之后识别、替换或删除该块。
常用示例
下面在目标主机的 /etc/hosts 中维护两条解析记录。修改系统文件通常需要提升权限,因此示例加入 --become。
ansible all --become -m ansible.builtin.blockinfile -a 'path=/etc/hosts block="10.0.0.10 app.internal
10.0.0.11 db.internal"'预期输出:首次写入时目标主机通常显示 CHANGED;使用相同参数再次执行且文件未被其他操作修改时,应显示 SUCCESS 且 changed 为 false。具体主机名和输出格式取决于 inventory 与 Ansible 版本。
<HOST> | CHANGED => {
"changed": true,
...
}可在目标主机读取标记及块内容进行验证:
ansible all --become -m ansible.builtin.command -a 'cat /etc/hosts'预期结果:输出中包含 10.0.0.10 app.internal、10.0.0.11 db.internal,并可看到 blockinfile 创建的受管块标记;系统原有的其他内容仍然保留。
风险与恢复
blockinfile 适合管理连续文本块,不适合精确修改单个配置项。多人或多个自动化任务同时维护同一文件时,应避免使用相同标记管理不同内容,否则可能互相覆盖。
需要撤销该受管块时,可对同一路径和对应标记使用 state=absent;如果文件属于关键系统配置,变更前还应保留可恢复副本,并在修改后执行该配置对应的语法检查或服务验证。
ansible <host-pattern> -m ansible.builtin.fetch -a 'src=<src> dest=<dest>'把目标主机上的文件传回控制节点并按主机组织目录;适合收集日志、配置和诊断产物,不适合大规模目录同步。
从主机获取文件
需要把远程主机上的日志、配置或诊断文件收集到 Ansible 控制节点时使用 ansible.builtin.fetch。它执行的是远程到本地的拉取,并默认按主机和源路径组织文件,适合从多台机器集中取证或归档单个文件。
基本语法
ansible <host-pattern> -m ansible.builtin.fetch -a 'src=<src> dest=<dest>'src 是目标主机上的源文件路径,dest 是控制节点上的目标目录或路径。默认行为会保留主机名和远程路径层级,因此对多个主机执行时可以避免同名文件直接互相覆盖。
常用示例
从所有匹配主机拉取 /var/log/syslog 到控制节点当前目录下的 artifacts:
ansible all -m ansible.builtin.fetch -a 'src=/var/log/syslog dest=./artifacts/'预期输出:成功获取文件的主机会返回 SUCCESS,首次复制或本地目标内容发生变化时 changed 通常为 true。实际主机名、校验值和本地路径随 inventory、环境及 Ansible 版本而变化。
<HOST> | SUCCESS => {
"changed": true,
...
}在控制节点检查实际生成的文件:
find ./artifacts -type f -print预期结果:能看到每台成功执行主机对应的已拉取文件路径;默认目录结构中包含主机及源文件路径信息,具体 <HOST> 由 inventory 决定。
./artifacts/<HOST>/var/log/syslog权限与边界
远程用户必须能够读取 src。读取受保护文件时可按权限策略使用 --become,但应确保控制节点上的落盘目录本身受到适当保护,尤其是收集可能含密钥、令牌或用户数据的配置和日志时。
fetch 主要用于文件拉取,不用于递归同步大型目录。需要收集目录时,应根据文件规模选择归档后拉取或其他同步方案,避免把大量文件逐个当作简单诊断产物处理。
软件包与系统
ansible <host-pattern> -m ansible.builtin.package -a 'name=<name> state=<state>'通过统一接口管理常见系统软件包;适合不想绑定具体发行版时使用,复杂仓库或发行版专属参数应选专用模块。
管理软件包
需要用同一条任务适配不同 Linux 发行版的软件包管理器时使用 ansible.builtin.package。它提供统一的软件包安装、升级和删除入口,底层会调用目标主机对应的软件包模块;需要 APT、DNF 等专属参数时应改用相应专用模块。
基本语法
ansible <host-pattern> -m ansible.builtin.package -a 'name=<name> state=<state>'name 指定软件包名称,名称必须能被目标主机的软件包管理器识别。state 决定目标状态,常用值包括 present、absent 和 latest;其中 latest 可能触发升级,生产环境使用前应确认版本策略。
安装并验证
以下命令确保清单中 all 匹配的主机已安装 curl:
ansible all -m ansible.builtin.package -a 'name=curl state=present'预期结果:成功主机返回 SUCCESS;首次安装通常显示 changed: true,软件包原本已满足要求时通常为 changed: false。具体返回内容会因目标系统的软件包管理器而不同。
继续验证命令是否可用:
ansible all -m ansible.builtin.command -a 'curl --version'预期结果:成功主机返回 SUCCESS,并在 stdout 中出现已安装的 curl 版本信息;版本号取决于目标主机的软件源。
风险与边界
package 适合跨发行版表达共同的软件包状态,但不会消除发行版之间的软件包名称、仓库配置和版本规则差异。删除软件包前应先确认依赖关系;使用 state=latest 前应评估升级影响。若任务依赖仓库缓存刷新、特定版本选择或发行版专属行为,应使用对应的软件包模块并单独验证。
ansible <host-pattern> -m ansible.builtin.apt -a 'name=<name> state=<state>'管理 Debian 系软件包及其安装状态;适合需要 apt 专属能力的场景,并应结合仓库与缓存策略处理版本和更新问题。
管理 APT 软件包
目标主机使用 APT,且需要明确控制 Debian 或 Ubuntu 软件包状态时使用 ansible.builtin.apt。除了安装和删除,它还适合需要 APT 缓存刷新等专属能力的任务;执行前应确认目标主机的软件源配置可用。
基本语法
ansible <host-pattern> -m ansible.builtin.apt -a 'name=<name> state=<state>'name 指定 APT 软件包名称,state=present 确保软件包已安装,state=absent 确保其被移除,state=latest 请求升级到当前软件源提供的最新版本。需要先刷新软件包索引时,可使用 update_cache=yes。
安装并验证
以下命令确保 all 匹配的 Debian/Ubuntu 主机已安装 curl:
ansible all -m ansible.builtin.apt -a 'name=curl state=present'预期结果:成功主机返回 SUCCESS;需要安装时通常显示 changed: true,已经处于目标状态时通常显示 changed: false。
安装失败且怀疑软件包索引过旧时,可先刷新缓存并安装:
ansible all -m ansible.builtin.apt -a 'name=curl state=present update_cache=yes'预期结果:APT 软件包索引被刷新,并确保 curl 已安装;最终是否显示变更取决于缓存和软件包原有状态。
可进一步验证实际命令:
ansible all -m ansible.builtin.command -a 'curl --version'预期结果:成功主机的 stdout 中出现 curl 版本信息,具体版本由目标主机配置的软件源决定。
风险与恢复
update_cache=yes 会访问已配置的软件源,仓库不可达、签名异常或源配置错误都可能导致任务失败。state=latest 可能升级现有软件包,不应在未确认版本兼容性的情况下批量执行。误删软件包后,可重新以 state=present 安装;若必须锁定具体版本,应先确认目标仓库确实提供该版本,再制定版本约束。
ansible <host-pattern> -m ansible.builtin.dnf -a 'name=<name> state=<state>'管理使用 DNF 的 RPM 系发行版软件包;适合安装、删除和升级软件,具体仓库与版本约束应显式写入任务。
管理 DNF 软件包
需要在使用 DNF 的受管主机上安装、删除或更新 RPM 软件包时使用 ansible.builtin.dnf。模块按声明的目标状态执行,重复运行时若软件包已经满足要求,通常不会产生额外变更。
基本语法
ansible <host-pattern> -m ansible.builtin.dnf -a 'name=<name> state=<state>'name 指定软件包名称;state=present 确保已安装,state=absent 确保已删除,state=latest 请求更新到当前可用的最新版本。实际可安装版本由目标主机启用的软件仓库决定。
安装并验证
先确认清单中的目标主机可达,再安装 vim-enhanced:
ansible all -m ansible.builtin.dnf -a 'name=vim-enhanced state=present'
ansible all -m ansible.builtin.command -a 'rpm -q vim-enhanced'预期结果:安装任务成功时主机会返回 SUCCESS;首次安装通常显示发生变更,已经安装则通常不变。验证命令返回已安装的软件包名称及版本,例如具体版本字符串;版本会随发行版和仓库变化。
权限与版本边界
软件包管理通常需要管理员权限;当前连接用户没有相应权限时,应按既有 Ansible 权限提升策略使用 --become。如果部署要求固定版本,应在 name 中显式使用目标系统和仓库支持的版本写法,不要用 state=latest 代替版本约束。
服务与进程
ansible <host-pattern> -m ansible.builtin.service -a 'name=<name> state=<state>'以统一方式启动、停止或重启服务;适合基础服务控制,遇到 systemd 专属能力时应改用 systemd 模块获取更多参数。
管理服务状态
需要跨不同服务管理器统一启动、停止或重启服务时使用 ansible.builtin.service。它适合基础状态控制;如果任务依赖 systemd 专属行为,应使用对应的 systemd 模块处理。
基本语法
ansible <host-pattern> -m ansible.builtin.service -a 'name=<name> state=<state>'name 是目标系统识别的服务名。常用状态包括 started、stopped、restarted 和 reloaded:前两者用于确保最终状态,后两者分别请求重启和重新加载服务配置。
启动并验证
下面确保 nginx 已启动,再通过服务管理器查询状态:
ansible all -m ansible.builtin.service -a 'name=nginx state=started'
ansible all -m ansible.builtin.command -a 'systemctl is-active nginx'预期结果:启动任务成功时返回 SUCCESS;若服务原本已经运行,通常不会发生状态变更。在使用 systemd 且服务正常运行的目标主机上,验证命令的标准输出为:
active第二条验证命令仅适用于使用 systemd 的目标主机;其他服务管理器应使用其对应的状态查询方式。
风险与恢复
服务控制通常需要管理员权限,没有权限时应按既有策略使用 --become。state=restarted 会主动重启服务,即使服务当前正在运行,也可能造成短暂连接中断;仅需让服务保持运行时优先使用 state=started。
ansible <host-pattern> -m ansible.builtin.systemd_service -a 'name=<name> state=<state>'针对 systemd 管理服务状态、开机启动和守护进程配置;适合主流 Linux 服务器,复杂 unit 操作可配合 daemon_reload。
管理 systemd 服务
需要批量启动、停止、重启 systemd 服务,或调整开机自启状态时使用 ansible.builtin.systemd_service。模块以 systemd 为目标执行幂等管理,适合直接确认服务应处于什么状态,而不是手工调用 systemctl。
基本语法
ansible <host-pattern> -m ansible.builtin.systemd_service -a 'name=<name> state=<state>'name 指定 systemd unit 名称;state 常用 started、stopped、restarted 或 reloaded。需要同时控制开机启动时增加 enabled=true 或 enabled=false。
启动并设置开机自启
ansible all -m ansible.builtin.systemd_service -a 'name=nginx state=started enabled=true'预期结果:成功主机返回 SUCCESS,结果中的 changed 表示本次是否实际修改了服务状态或启用状态;已经满足要求时通常不会重复执行无意义的启动操作。
可进一步读取服务事实确认当前状态:
ansible all -m ansible.builtin.service_facts预期结果:成功主机返回服务事实,可在 ansible_facts.services 中查找对应 nginx unit;实际 unit 键名取决于目标系统。
重新加载 unit 配置
修改 unit 文件或 drop-in 配置后,可让 systemd 重新读取配置并重启服务:
ansible all -m ansible.builtin.systemd_service -a 'name=nginx daemon_reload=true state=restarted'预期结果:systemd 先执行 daemon reload,再重启 nginx;成功主机返回 SUCCESS。如果只需要让服务重新读取自身配置且该 unit 支持 reload,应使用 state=reloaded,避免不必要的进程重启。
风险与恢复
state=restarted 会实际重启服务,即使它当前已经运行,也可能造成短暂连接中断。批量作用于 all 前,应先缩小 host pattern 验证目标主机,并确认服务名在目标系统存在。
误停服务时,可重新执行 state=started;误关闭开机自启时,可执行 enabled=true 恢复。
ansible <host-pattern> -m ansible.builtin.reboot安全地触发目标主机重启并等待重新可连接;适合内核升级或必须重启的变更,执行前应确认连接方式和业务影响。
重启主机
完成内核升级、底层系统更新或其他必须通过整机重启生效的变更后,可用 ansible.builtin.reboot 触发远端重启并等待主机重新可用。与直接执行 reboot 命令相比,它会处理重启后的连接等待,更适合自动化流程。
执行前确认
重启会终止目标主机上的现有进程和连接。先确认 Ansible 当前能够连接目标,并核对实际命中的主机范围:
ansible all --list-hosts
ansible all -m ansible.builtin.ping预期结果:--list-hosts 列出本次会匹配的主机;连通且 Python 等执行条件正常的目标对 ping 模块返回 pong。若列表包含不应重启的服务器,应先调整 host pattern,而不是继续执行。
执行重启
ansible all -m ansible.builtin.reboot预期结果:Ansible 请求目标主机重启,连接会暂时中断;主机恢复并通过模块的重启后检查后,任务返回成功。具体耗时取决于硬件、操作系统、启动服务和网络环境。
重启后验证
再次执行连通性检查,确认 Ansible 已能正常管理目标:
ansible all -m ansible.builtin.ping预期结果:已恢复的目标返回 pong。这只验证 Ansible 管理通道及基本执行条件,不代表业务服务已经完全恢复,应按业务自身的健康检查继续确认应用状态。
风险与恢复
重启不是可直接撤销的操作。若主机在重启后无法重新连接,应通过云平台、虚拟化平台、带外管理或现场控制台检查启动失败、网络配置和文件系统等问题;这些恢复能力必须在执行批量重启前确认可用。
用户与权限
ansible <host-pattern> -m ansible.builtin.user -a 'name=<name> state=present'创建或维护系统用户及其属性;适合服务账号、登录账号和权限初始化,涉及密码或密钥时应同步控制敏感数据。
创建用户
需要批量创建或维护 Linux/Unix 系统账号时使用 ansible.builtin.user。设置 state=present 后,Ansible 会让目标用户达到期望状态;用户已经存在且属性一致时不会重复创建。
基本语法
ansible <host-pattern> -m ansible.builtin.user -a 'name=<name> state=present'<host-pattern> 决定操作哪些清单主机,name 指定用户名,state=present 表示确保该用户存在。执行远程用户管理通常需要足够权限;当前连接用户权限不足时,应按既有 Ansible 提权配置使用 --become。
关键选项
name:要管理的用户名,创建用户时必须明确指定。state=present:确保用户存在;若已存在,则按给出的属性维护用户。create_home=true:创建用户时要求建立家目录,适合需要登录或保存用户级文件的账号。groups:配置附加组。与append搭配时要特别确认是否保留用户已有的附加组。
创建带家目录的用户
ansible all -m ansible.builtin.user -a 'name=appuser state=present create_home=true'预期结果:成功主机返回模块执行结果;首次创建通常表现为发生变更,再次以相同参数执行时应表现为未发生变更。不同 Ansible 版本和输出回调插件的显示格式可能不同,因此不要依赖固定的整段终端文本。
可进一步读取目标账号确认是否存在:
ansible all -m ansible.builtin.command -a 'id appuser'预期结果:成功主机返回 appuser 对应的 UID、主组和附加组信息;UID、GID 等数值由目标系统实际分配,可能不同。
风险与恢复
修改账号的组、Shell、UID 等属性可能影响文件权限和服务运行,不要在未确认现有状态时批量覆盖。密码等敏感值也不应直接暴露在命令历史、日志或普通变量文件中。
若只是误创建了账号,应先确认该账号没有承载进程、文件或业务数据,再使用 state=absent 处理删除;是否同时删除家目录需要单独评估,避免把恢复账号问题扩大为数据删除问题。
ansible <host-pattern> -m ansible.builtin.group -a 'name=<name> state=<state>'创建、删除或维护本地用户组;适合为应用进程建立稳定的权限边界,并与 user、file 等模块组合完成权限配置。
管理用户组
需要在一批 Linux/Unix 主机上统一创建、删除或维护本地用户组时使用 ansible.builtin.group。它适合先建立稳定的组身份,再交给用户和文件权限配置引用。
基本语法
ansible <host-pattern> -m ansible.builtin.group -a 'name=<name> state=<state>'name 指定组名,state 决定目标状态。管理系统用户组通常需要足够权限;连接用户没有相应权限时,应按照现有 Ansible 提权配置使用 --become。
关键选项
name:需要管理的组名。state=present:确保组存在,重复执行不会重复创建同名组。state=absent:确保组不存在,删除前应检查用户、文件和服务是否仍依赖该组。gid:需要固定数字 GID 时使用;应先确认目标主机不存在冲突。
创建用户组
ansible all -m ansible.builtin.group -a 'name=appgroup state=present'预期结果:不存在 appgroup 的主机会创建该组并报告发生变更;已经具有期望状态的主机应报告未发生变更。具体终端格式受 Ansible 版本和输出回调插件影响。
可读取系统组数据库验证结果:
ansible all -m ansible.builtin.command -a 'getent group appgroup'预期结果:成功主机返回 appgroup 的组数据库记录,其中 GID 是目标系统的实际值;若未显式指定 gid,各主机分配的数字可能不同。
风险与恢复
删除用户组前应检查它是否仍是用户的组身份,或被文件、目录和服务配置引用。只删除组记录不会自动解决已有文件上的数字 GID 归属问题。
如果误删了仍需使用的组,应优先按原组名重新创建;依赖固定 GID 的环境还必须确认并恢复原 GID,再检查相关用户和文件权限,避免仅恢复名称却留下权限不一致。