基础设施即代码 / 知识点
Ansible 常用模块速查
用户与权限
ansible <host-pattern> -m ansible.posix.authorized_key -a 'user=<user> key=<key>'维护用户的 authorized_keys 内容;适合批量下发运维或部署公钥,实施前应确认 collection 已安装且用户家目录可写。
配置 SSH 公钥
需要批量为远程用户加入或维护 SSH 公钥时使用 ansible.posix.authorized_key。模块会按声明管理 authorized_keys 中的密钥,适合替代逐台登录后手工追加。
使用前确认
该模块属于 ansible.posix collection,不是 ansible-core 自带模块。先在控制端确认 collection 可用,并确认目标用户已经存在、Ansible 连接账号有权修改其授权密钥文件。
ansible-galaxy collection list ansible.posix预期结果:列表中能找到 ansible.posix 及其已安装版本;具体版本号和安装路径因环境而异。若没有结果,可按项目锁定的版本要求安装对应 collection。
基本语法
ansible <host-pattern> -m ansible.posix.authorized_key -a 'user=<user> key=<key>'user:接收公钥的远程用户,必须是目标主机上的有效账号。key:要写入的完整 SSH 公钥文本,例如以ssh-ed25519开头的公钥。state=present:确保指定公钥存在;这是常见的下发方式。state=absent:删除匹配的公钥,撤销访问时使用。
下发并验证公钥
下面使用示例公钥演示幂等写入。实际使用时应替换为真实公钥;示例中的密钥内容仅用于展示参数格式。
ansible all -m ansible.posix.authorized_key -a 'user=deploy state=present key="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDemoKeyForDocumentationOnly deploy@example"'预期输出:成功主机会返回 SUCCESS;首次加入通常显示 changed: true,相同密钥再次执行通常显示 changed: false。返回 JSON 的具体字段顺序和附加字段可能随 Ansible 版本变化。
可进一步检查远程文件是否包含对应公钥:
ansible all -m ansible.builtin.shell -a 'grep -F "AAAAC3NzaC1lZDI1NTE5AAAAIDemoKeyForDocumentationOnly" ~/.ssh/authorized_keys'预期输出:目标用户上下文正确时会显示匹配的公钥行;若 Ansible 当前连接用户与 deploy 不同,应改为检查 deploy 实际的 authorized_keys 路径,并确保具备读取权限。
风险与恢复
批量替换或删除公钥可能导致 SSH 访问中断。修改前应保留至少一种已验证的管理通道,不要在尚未验证新密钥可登录时移除旧密钥。
需要撤销本次加入的密钥时,用完全匹配的公钥配合 state=absent 删除,再验证仍保留预期的管理密钥。若目标用户家目录、.ssh 或 authorized_keys 不可写,应先修复用户、权限或提权配置,而不是反复执行模块。
ansible <host-pattern> -m ansible.builtin.cron -a 'name=<name> minute=<minute> job=<job>'管理用户级 crontab 定时任务;适合简单周期任务,生产环境应关注环境变量、输出重定向、锁机制和任务失败后的观测。
执行定时任务
需要批量创建、修改或删除用户的周期任务时使用 ansible.builtin.cron。模块按 name 标识任务,可重复执行而不持续追加相同条目,适合维护简单的 crontab 任务。
基本语法
ansible <host-pattern> -m ansible.builtin.cron -a 'name=<name> minute=<minute> job=<job>'name:任务标识,也是后续修改或删除该任务的重要匹配依据。minute、hour、day、month、weekday:定义执行时间;未指定的时间字段按模块规则处理,生产配置应显式写出需要约束的字段。job:实际执行的命令。应使用明确路径,并根据需要处理标准输出和错误输出。user:指定维护哪个用户的 crontab;修改其他用户时通常需要相应提权权限。state=absent:按name删除由模块管理的任务。
创建凌晨清理任务
以下命令每天 03:00 执行清理脚本,并把标准输出和标准错误追加到日志文件。
ansible all -m ansible.builtin.cron -a 'name="cleanup temp" minute="0" hour="3" job="/usr/local/bin/cleanup.sh >> /var/log/cleanup.log 2>&1"'预期输出:首次创建时成功主机通常返回 SUCCESS 且结果包含 changed: true;配置已经一致时再次执行通常为 changed: false。具体 JSON 字段和显示格式可能随 Ansible 版本变化。
可直接读取当前连接用户的 crontab 验证任务:
ansible all -m ansible.builtin.command -a 'crontab -l'预期输出:可看到 Ansible 为 cleanup temp 管理的标识以及对应的 0 3 定时任务。若通过 user 管理其他账号,应以相应权限读取该用户的 crontab。
生产环境注意事项
Cron 的运行环境通常比交互式 Shell 精简。脚本应使用绝对路径,或在任务中显式准备所需环境;不要假设登录 Shell 中的 PATH、语言运行时初始化或其他环境变量自动存在。
任务执行时间可能超过调度周期时,应在脚本或命令层加入适合业务的锁机制,避免多个实例重叠。关键任务还应保留日志或接入监控,因为 Ansible 成功写入 crontab 只证明配置完成,并不证明未来每次任务都执行成功。
删除与恢复
删除任务时保持 name 与创建时一致,并设置 state=absent:
ansible all -m ansible.builtin.cron -a 'name="cleanup temp" state=absent'预期输出:存在该任务时通常返回 changed: true;已经不存在时通常返回 changed: false。误删后可重新执行原创建命令恢复任务。
网络与远程资源
ansible <host-pattern> -m ansible.builtin.get_url -a 'url=<url> dest=<dest>'从 HTTP 或 HTTPS 地址下载文件到目标主机;适合安装包、配置和静态资源获取,生产环境建议同时校验校验和。
下载远程文件
需要让一批受管主机直接从 HTTP 或 HTTPS 地址取得安装包、配置或静态资源时使用 ansible.builtin.get_url。文件下载发生在目标主机上;生产环境可配合 checksum 校验内容,避免只确认“下载成功”却使用了错误文件。
基本语法
ansible <host-pattern> -m ansible.builtin.get_url -a 'url=<url> dest=<dest>'<host-pattern> 决定执行范围,url 指定远程资源地址,dest 指定受管主机上的目标文件或目录。执行账户还必须拥有目标路径的写权限。
关键选项
url:待下载资源的 HTTP 或 HTTPS URL。dest:受管主机上的目标路径;不是运行 Ansible 命令的控制节点路径。checksum:按指定摘要验证下载内容,例如sha256:<digest>;校验不一致时任务失败。force:控制是否强制重新下载;是否需要开启应根据资源更新方式决定。mode:设置下载后文件的权限模式,需要固定权限时显式指定。
下载并验证
下面以固定 SHA-256 摘要为例。<SHA256> 应替换为发布方提供或通过可信渠道获得的真实摘要。
ansible all -m ansible.builtin.get_url -a 'url=https://example.com/app.tar.gz dest=/tmp/app.tar.gz checksum=sha256:<SHA256>'预期输出:成功主机通常返回 SUCCESS,结果中的 changed 表示本次是否改变了目标文件;具体摘要、大小和其他字段会随 Ansible 版本及文件状态变化。
<HOST> | SUCCESS => {
"changed": <true-or-false>,
...
}随后可独立确认文件存在:
ansible all -m ansible.builtin.stat -a 'path=/tmp/app.tar.gz'预期结果:目标主机返回 SUCCESS,并且 stat.exists 为 true。文件大小、校验和等动态值以实际返回为准。
风险与恢复
下载地址可访问不代表内容可信。安装包等高风险资源应使用可信 HTTPS 来源并配置 checksum;不要用关闭证书验证的方式长期绕过 TLS 问题。写入已有文件前还要确认 dest,避免覆盖业务文件。
若下载失败,先检查目标主机的 DNS、代理、TLS 信任和出站网络,而不是只检查控制节点。误写了目标文件时,应从可信备份或已验证版本恢复,再用 stat 或业务自身的校验方式确认恢复结果。
ansible <host-pattern> -m ansible.builtin.uri -a 'url=<url> method=<method>'发起 HTTP 请求并检查状态码、响应内容和认证信息;适合健康检查、Webhook、内部 API 调用和发布流程验证。
调用 HTTP API
需要从执行模块的主机发起 HTTP 请求并检查接口状态时使用 ansible.builtin.uri。它适合健康检查、Webhook 和发布后验证;请求从匹配到的目标主机发出,因此 localhost 与远程受管主机可能看到完全不同的网络环境。
基本语法
ansible <host-pattern> -m ansible.builtin.uri -a 'url=<url> method=<method>'url 指定请求地址,method 指定 HTTP 方法。只做可达性检查时通常不必返回正文;需要读取响应内容时再启用 return_content。
关键选项
method:HTTP 方法,例如GET、POST、PUT或DELETE;应与服务端接口约定一致。status_code:定义哪些 HTTP 状态码视为成功;默认行为适合常见成功响应,但接口使用其他成功码时应显式配置。return_content:是否把响应正文包含在模块结果中;排查接口内容时可开启。headers:发送认证信息、内容类型或其他 HTTP 请求头。body与body_format:用于提交请求体;JSON API 常使用body_format=json。timeout:限制连接等待时间,避免不可达接口长期阻塞任务。
检查接口状态
以下请求由 localhost 发出,并明确要求 HTTP 200 才算成功:
ansible localhost -m ansible.builtin.uri -a 'url=https://example.com method=GET status_code=200 return_content=false'预期输出:接口返回 HTTP 200 时任务为 SUCCESS,结果中可读取 status;响应头等其他字段会随服务端和 Ansible 版本变化。
localhost | SUCCESS => {
"changed": false,
"status": 200,
...
}若实际接口预期返回其他成功状态,应把对应状态码写入 status_code,不要为了让任务通过而忽略状态检查。
失败定位
收到 401 或 403 时检查认证信息和权限;收到 404 时检查 URL 与路由;5xx 通常需要结合服务端日志判断。连接超时、DNS 解析失败和 TLS 校验失败则发生在取得有效 HTTP 响应之前,应从执行模块的那台主机检查网络环境。
风险与恢复
GET 健康检查通常只读,但 POST、PUT、PATCH、DELETE 是否会修改状态完全取决于目标 API。调用写接口前应确认其幂等性、重试语义和回滚接口;请求失败后不要盲目重复提交,否则可能重复创建资源或触发 Webhook。
ansible <host-pattern> -m ansible.builtin.wait_for -a 'port=<port> host=<host> state=started'等待指定 TCP 端口达到预期状态;适合服务启动后再继续部署或验证,能减少固定 sleep 带来的竞态和无效等待。
等待端口可用
服务启动后需要确认 TCP 端口已经能够建立连接时使用 ansible.builtin.wait_for。它会持续探测条件,成功后才结束,比固定等待若干秒更适合处理启动耗时不确定的服务。
基本语法
ansible <host-pattern> -m ansible.builtin.wait_for -a 'port=<port> host=<host> state=started'host 指定要探测的地址,port 指定 TCP 端口,state=started 表示等待端口进入可连接状态。探测动作发生在模块实际执行所在的主机上,因此 127.0.0.1 指向该执行环境自身。
关键选项
host:等待的主机地址;应明确目标服务从模块执行位置是否可达。port:等待的 TCP 端口。state=started:等待端口开始接受连接。timeout:最长等待秒数;条件在期限内未满足时任务失败。delay:开始检查前先等待指定秒数,适合明确存在启动缓冲期的场景。
常用示例
以下命令在 localhost 上等待本机 8080 端口可用,最长等待 30 秒:
ansible localhost -m ansible.builtin.wait_for -a 'host=127.0.0.1 port=8080 state=started timeout=30'预期结果:如果 30 秒内端口可连接,Ansible 返回成功,结果中可看到 changed 为 false;实际等待时间等动态字段可能不同。
localhost | SUCCESS => {
"changed": false,
...
}若超时仍无法连接,任务返回失败而不是继续后续依赖该端口的操作。具体错误文本可能随 Ansible 版本和连接条件不同。
风险与边界
端口可连接只证明 TCP 监听已经建立,不等于应用完成业务初始化。例如 HTTP 服务可能已经监听端口,但数据库迁移或缓存预热仍未完成;需要业务级就绪判断时,应继续检查对应的健康接口或应用条件。
等待失败时先确认目标服务进程、监听地址、防火墙和网络可达性,再重新执行等待命令;单纯增大 timeout 不能修复服务未启动或地址配置错误。
部署与交付
ansible <host-pattern> -m ansible.builtin.unarchive -a 'src=<src> dest=<dest>'将 tar、zip 等归档内容解压到目标主机;适合应用发布包和离线资源部署,可结合 remote_src 表示源文件已在远端。
解压归档文件
需要把应用发布包或离线资源展开到目标目录时使用 ansible.builtin.unarchive。源归档既可以由控制端传到目标主机,也可以通过 remote_src=true 明确表示文件已经存在于远端。
基本语法
ansible <host-pattern> -m ansible.builtin.unarchive -a 'src=<src> dest=<dest>'src 是归档文件来源,dest 是解压目录。默认情况下 src 按控制端文件处理;当归档已经位于目标主机时,应设置 remote_src=true。
关键选项
src:归档文件路径;其所在位置受remote_src影响。dest:目标主机上的解压目录;应事先确保目录存在并具有合适权限。remote_src=true:表示src已经存在于目标主机,不再从控制端复制。creates:指定一个路径;该路径已经存在时可跳过解压,适合为部署增加明确的幂等条件。
常用示例
假设 /tmp/app.tar.gz 已经存在于各目标主机,并且 /opt/app 已准备好,执行:
ansible all -m ansible.builtin.unarchive -a 'src=/tmp/app.tar.gz dest=/opt/app remote_src=true'预期结果:归档内容被展开到 /opt/app。发生需要落盘的变化时,成功结果通常显示 changed 为 true;若目标内容已经满足模块判断条件,也可能为 false,具体结果取决于归档内容和目标状态。
<HOST> | CHANGED => {
"changed": true,
...
}可在目标主机上进一步验证关键文件是否存在,例如:
ansible all -m ansible.builtin.stat -a 'path=/opt/app'预期结果:成功响应中的 stat.exists 为 true,表示目标路径存在;若要验证发布是否完整,应把路径替换为归档中预期存在的关键文件。
风险与恢复
解压可能覆盖目标目录中的同名文件,因此发布前应确认归档内部路径和 dest 是否匹配预期。不要把包含未知路径结构的归档直接释放到正在使用的生产目录。
需要可恢复发布时,可先解压到独立版本目录,验证后再切换应用使用的版本。若直接覆盖现有目录,应在执行前准备可恢复的旧版本或备份;解压失败后先处理磁盘空间、权限、归档完整性或目标路径问题,再重新执行。
ansible <host-pattern> -m ansible.posix.synchronize -a 'src=<src> dest=<dest>'基于 rsync 同步目录或文件,适合大量文件和增量传输;它依赖 rsync 环境,权限、删除策略和源目标方向必须确认。
同步目录内容
需要把控制端的大量文件高效增量同步到远端主机时使用 ansible.posix.synchronize。它封装 rsync,适合部署目录、静态资源和批量文件,但执行前要确认源目标方向、rsync 可用性以及删除策略。
基本语法
ansible <host-pattern> -m ansible.posix.synchronize -a 'src=<src> dest=<dest>'默认场景下,src 位于执行 Ansible 的控制端,dest 位于目标主机。ansible.posix.synchronize 属于 ansible.posix collection,并非 ansible-core 内置模块;控制端需要可用的 rsync,目标端通常也需要安装 rsync。
关键选项
src:源文件或目录。目录末尾是否带/会影响同步的是目录本身还是目录中的内容,应按 rsync 语义确认。dest:目标路径,需要确保远端连接用户拥有相应写权限。delete=true:删除目标端中源端不存在的文件,使目标更接近源端镜像。该选项具有破坏性,启用前应先确认目标路径。recursive:控制目录递归同步,通常保持默认行为即可。
常用示例
先准备一个可识别的源文件,再同步整个目录。示例假设 ansible.posix collection、两端 rsync 和 inventory 已准备好,并且远端用户可写 /tmp/app/。
mkdir -p /tmp/release
printf 'release-ok\n' > /tmp/release/version.txt
ansible all -m ansible.posix.synchronize -a 'src=/tmp/release/ dest=/tmp/app/'
ansible all -m ansible.builtin.command -a 'cat /tmp/app/version.txt'预期结果:同步任务成功后,验证命令返回 release-ok;Ansible 输出中的主机名及任务状态字段会随 inventory 和环境不同而变化。
release-ok风险与恢复
synchronize 的传输方向和路径尾部斜杠都可能改变结果,生产目录首次同步前应先在临时目标验证。尤其不要在未核对 dest 时启用 delete=true,否则目标端额外文件可能被删除。
检查与排障
ansible <host-pattern> -m ansible.builtin.find -a 'paths=<paths> patterns=<patterns>'按路径、名称、大小或时间等条件搜索远端文件;适合日志定位、清理前盘点和批量运维检查,不直接改变文件状态。
收集文件列表
需要在远端主机按目录、文件名或时间条件盘点文件时使用 ansible.builtin.find。它只负责查找并返回匹配信息,不会删除或修改文件,因此适合在清理日志、归档或批处理之前先确认操作范围。
基本语法
ansible <host-pattern> -m ansible.builtin.find -a 'paths=<paths> patterns=<patterns>'paths:要搜索的远端路径。patterns:文件名匹配模式,例如*.log。Shell 调用时应注意引号,避免通配符被本地 Shell 提前展开。age:按文件时间筛选,例如7d表示达到指定天数条件。age_stamp:指定age使用的时间属性;mtime表示文件内容修改时间。
常用示例
下面查找 /var/log 中修改时间达到 7 天且名称匹配 *.log 的文件。命令只返回匹配结果,不执行删除。
ansible all -m ansible.builtin.find -a 'paths=/var/log patterns="*.log" age=7d age_stamp=mtime'预期结果:执行成功时 Ansible 返回模块结果,其中 matched 表示匹配数量,files 保存匹配文件的详细信息。实际数量、路径、时间和其他元数据取决于目标主机,因此不应预设固定值。
<HOST> | SUCCESS => {
"matched": <MATCHED_COUNT>,
"files": [<MATCHED_FILE_OBJECTS>]
}读取结果
重点检查 matched 和 files:前者用于快速判断命中规模,后者用于确认具体路径及文件元数据。准备后续清理时,应先核对这些结果,再把确认过的路径交给删除或归档任务。
边界与风险
搜索范围过大时,递归扫描会增加远端文件系统遍历成本。应尽量把 paths 限定到目标目录,并用 patterns、age 等条件缩小结果集。若结果与预期不符,先调整筛选条件重新执行即可;由于该模块本身不改变文件状态,无需执行数据恢复。
ansible <host-pattern> -m ansible.builtin.debug -a 'msg=<msg>'输出固定消息或变量值以辅助排查任务执行结果;适合验证变量、条件和中间状态,敏感信息不应直接打印到日志。
输出调试信息
需要确认 Ansible 已执行到某个检查点,或快速查看变量和中间状态时使用 ansible.builtin.debug。临时诊断完成后应检查并移除可能泄露敏感数据的调试输出。
基本语法
ansible <host-pattern> -m ansible.builtin.debug -a 'msg=<msg>'msg 用于输出指定消息。执行 ad hoc 命令时,目标主机必须能被当前 inventory 或主机模式解析;使用 localhost 可在本机快速验证模块行为。
输出固定消息
ansible localhost -m ansible.builtin.debug -a 'msg="deployment check started"'预期结果:任务成功并在结果中显示指定消息。Ansible 版本及输出回调插件不同会影响外围格式,但核心结果应包含类似内容:
localhost | SUCCESS => {
"msg": "deployment check started"
}如果需要进一步确认命令是否成功,可检查进程退出状态;成功执行通常返回退出码 0。
查看变量时的边界
在 Playbook 中调试变量时,debug 还支持 var 参数;它与这里的 msg 用法不同。不要为了查看密码、令牌、私钥或其他凭据而直接打印变量,因为调试结果可能进入终端记录、CI 日志或集中日志系统。
ansible <host-pattern> -m ansible.builtin.assert -a 'that=<condition>'显式检查运行前提或中间结果,不满足条件时让任务失败;适合发布门禁、环境校验和防止错误配置继续执行。
校验条件是否成立
需要在继续执行前验证变量、事实或运行条件时使用 ansible.builtin.assert。条件为真时检查通过;条件为假时任务失败,因此适合把错误配置挡在后续操作之前。
基本语法
ansible <host-pattern> -m ansible.builtin.assert -a 'that=<condition>'that 接收要判断的条件表达式。表达式依赖变量或 facts 时,必须确保这些数据在执行上下文中已经存在,否则检查可能因变量未定义而失败。
校验系统类型
下面的命令与条目中的快捷示例一致,通过 ansible_facts.os_family 检查目标是否属于 Debian 系列:
ansible localhost -m ansible.builtin.assert -a 'that="ansible_facts.os_family == Debian"'预期结果:当 ansible_facts.os_family 的值为 Debian 时,任务返回成功;具体外围格式会随 Ansible 版本和输出回调插件变化,核心状态应为成功。若条件不成立,任务返回失败并产生非零退出状态。
localhost | SUCCESS => {
"changed": false,
"msg": "All assertions passed"
}失败后的处理
断言失败本身不会修复环境,它的作用是阻止不满足前提的执行继续被当作成功处理。若检查依赖 facts,先确认目标主机可连接且 facts 可用;若条件写错,则修正表达式后重新执行检查。
ansible <host-pattern> -m ansible.builtin.set_fact -a '<key>=<value>'在当前主机上下文中创建运行时变量;适合把计算结果传递给后续任务,变量生命周期和覆盖关系应保持清晰。
设置运行时变量
需要在当前 Ansible 执行上下文中保存一个计算结果,并让后续任务按变量名读取时使用。ansible.builtin.set_fact 会把变量写入当前主机的事实变量上下文;它不是系统环境变量,也不会自动成为下一次独立命令执行的变量。
基本语法
ansible <host-pattern> -m ansible.builtin.set_fact -a '<key>=<value>'<host-pattern>:选择要设置变量的主机。<key>=<value>:变量名和值;变量名应保持稳定,避免覆盖已有变量造成歧义。
常用示例
ansible localhost -m ansible.builtin.set_fact -a 'deploy_env=staging'预期结果:命令执行成功,结果中可看到 ansible_facts,其中包含 deploy_env 为 staging。
localhost | SUCCESS => ...读取方法:在同一次 Playbook 执行中,后续任务可直接使用 {{ deploy_env }};单独再次运行一条新的 ansible 命令时,不应假定该变量仍然存在。
风险与边界
set_fact 的作用域和生命周期应结合 Playbook 执行流程理解。变量名与更高优先级变量冲突时可能被覆盖或产生难以排查的结果;需要跨次执行持久保存的数据,应使用事实缓存或其他持久化机制,而不是把 set_fact 当作长期存储。
ansible <host-pattern> -m ansible.builtin.setup收集目标主机的系统事实和硬件信息;适合判断操作系统、地址、CPU 等运行环境,数据量较大时应避免无必要的重复采集。
检查主机事实
需要确认目标主机的操作系统、网络地址、处理器等运行环境时使用。ansible.builtin.setup 会收集 Ansible facts;当只关心少量字段时应缩小采集范围,避免输出大量无关数据。
基本语法
ansible <host-pattern> -m ansible.builtin.setup主机模式决定收集哪些主机的事实;默认完整采集会返回较多信息。
常用示例
ansible localhost -m ansible.builtin.setup -a 'filter=ansible_distribution'预期结果:命令成功,并在返回的 ansible_facts 中看到与发行版相关的字段,例如 ansible_distribution;具体值取决于目标主机实际系统。
读取更多事实时,可直接执行:
ansible all -m ansible.builtin.setup预期结果:每台匹配主机返回一组 ansible_facts。完整输出通常较大,可先按字段筛选,再根据结果判断操作系统、地址或硬件环境。
风险与边界
完整 facts 采集的数据量可能较大,不必在每次排查中重复获取全部字段。过滤条件应以实际需要为准;不同操作系统、Ansible 版本和主机环境可提供的事实字段可能不同,不应把某个具体字段值当作固定结果。
ansible <host-pattern> -m ansible.builtin.service_facts收集主机服务及其状态信息;适合批量检查服务运行情况和编写条件判断,比直接解析 systemctl 文本输出更稳定。
获取服务清单
需要批量检查 Linux 主机上的服务名称、状态或为后续条件判断准备服务事实时使用。执行后,Ansible 会把服务信息写入返回结果中的 ansible_facts.services,便于后续任务直接引用。
基本语法
ansible <host-pattern> -m ansible.builtin.service_facts<host-pattern>:目标主机模式,例如all、web或单台主机名。ansible.builtin.service_facts:收集服务事实,不需要先执行systemctl再解析文本。
常用示例
ansible all -m ansible.builtin.service_facts预期结果:命令成功返回各目标主机的 Ansible 结果,其中事实数据包含 ansible_facts.services;该映射的具体服务名称和状态取决于目标主机当前环境。
需要在自动化任务中判断某个服务时,应读取该事实中的具体服务项,而不是依赖终端文本格式。
风险与边界
该模块主要负责收集事实,不负责启动、停止或重启服务。不同主机实际存在的服务及状态会不同,因此不要把某个固定服务名或固定状态写死为通用输出。若命令失败,先检查目标主机可达性、Python/Ansible 执行环境以及目标系统是否能正常提供服务事实。
系统资源
ansible <host-pattern> -m ansible.posix.mount -a 'path=<path> src=<src> fstype=<fstype> state=<state>'维护文件系统挂载及 fstab 配置;适合持久化磁盘、NFS 等场景,修改前应核对设备、文件系统类型和卸载影响。
管理挂载点
需要用 Ansible 统一维护挂载点以及对应的 fstab 配置时使用。执行前必须确认 path、src、fstype 与目标主机实际磁盘或 NFS 配置一致;错误参数可能造成挂载失败或影响持久化启动。
基本语法
ansible <host-pattern> -m ansible.posix.mount -a 'path=<path> src=<src> fstype=<fstype> state=<state>'path:挂载点目录。src:块设备、UUID、NFS 源等实际挂载来源。fstype:文件系统类型,例如目标环境实际使用的文件系统类型。state:控制挂载与配置状态;具体值应根据所需操作选择。
常用示例
下面是使用 state=present 维护 fstab 条目的片段示例;设备路径必须替换成目标主机实际存在的值。
ansible all -m ansible.posix.mount -a 'path=/data src=/dev/disk/by-id/<ID> fstype=xfs state=present'预期结果:任务成功后,目标主机对应的挂载配置进入 Ansible 所要求的存在状态;实际是否已经挂载取决于所使用的 state 语义以及目标主机当前状态。
可在目标主机上检查配置是否落盘:
ansible all -m ansible.builtin.command -a 'grep -F " /data " /etc/fstab'预期结果:成功时返回匹配 /data 的 fstab 配置行;具体字段内容取决于实际 src、fstype 和挂载选项。
风险与恢复
这是高风险系统操作。执行前先确认设备、文件系统类型、挂载点是否为空闲目录,并核对该挂载是否被业务进程使用。不要直接用未知设备测试,也不要在生产环境未经验证就切换到会立即挂载或卸载的状态。
发现配置错误时,先停止后续依赖该挂载点的自动化任务,再根据原始 fstab 配置恢复正确值;涉及正在使用的文件系统时,不要贸然卸载,应先确认进程、容量和业务影响。
ansible <host-pattern> -m ansible.builtin.hostname -a 'name=<name>'设置目标主机的系统主机名;适合新主机初始化和环境标准化,变更后应同步核对 DNS、inventory 名称及依赖配置。
修改主机名
需要批量设置 Linux 主机系统主机名时使用;执行后可直接用 Ansible 再次读取目标主机名确认结果。
基本语法
ansible <host-pattern> -m ansible.builtin.hostname -a 'name=<name>'<host-pattern> 指定目标主机或主机组,name 指定新的系统主机名。命令修改的是目标系统的 hostname,不会自动修改 DNS 或 Ansible inventory 中的主机标识。
高频示例
ansible all -m ansible.builtin.hostname -a 'name=app-01'
ansible all -m ansible.builtin.command -a 'hostname'预期结果:前一个任务成功完成后,后一个命令在每台目标主机上读取到对应的系统主机名;主机实际名称按 inventory 与目标环境而定。
验证与边界
如果 inventory 中仍使用旧名称,应同时检查相关配置、证书、DNS 或应用依赖。若只想修改 Ansible inventory 中的连接名称,不应使用该模块替代 inventory 配置。
ansible <host-pattern> -m ansible.builtin.reboot -a 'reboot_timeout=<seconds>'针对需要重启的变更设置明确等待时间并确认主机重新上线;适合内核、关键系统组件升级后的恢复性验证。
检查主机并重启
需要在变更后让目标主机重启,并等待 Ansible 确认主机重新可连接时使用。reboot_timeout 用于控制等待重启完成的时间范围。
基本语法
ansible <host-pattern> -m ansible.builtin.reboot -a 'reboot_timeout=<seconds>'执行前应确认目标主机允许重启、当前连接使用的账号具备相应权限,并将等待时间设置为符合主机实际启动速度的值。
高频示例
ansible all -m ansible.builtin.reboot -a 'reboot_timeout=300'预期结果:Ansible 对匹配的主机执行重启,并等待主机在设定的等待时间内重新上线;成功时任务应报告成功状态,具体显示内容随 Ansible 版本和目标环境而定。
风险与恢复
这是中断性操作,执行后目标主机会暂时失去连接。若任务因超时失败,先从带外管理、云控制台或主机本地确认机器是否已经完成启动,再检查 SSH、网络和 Ansible 连接条件后重新验证。
不要把 reboot_timeout 理解为所有启动问题的修复手段;服务未恢复、网络未就绪或认证失败时,应分别排查对应环节。