Ansible Playbook YAML 格式化工具
指导
Ansible Playbook YAML 格式化工具
粘贴任何 Ansible playbook 或任务文件,即可获得一致格式化的 YAML,任务键按标准顺序排列(name → module → args → loop → when → register → notify)。该工具会检测您粘贴的是 playbook 还是任务列表,验证结构,并提供 ansible-lint 风格提示——FQCN 模块名称、缺少 changed_when, command-instead-of-module,以及遗留 yes/no 真值——确保您的 playbook 首次审查即可通过。
如何使用
- 将您的 Ansible YAML 粘贴到输入框中——一个完整的
playbook.yml,一个角色的tasks/main.yml,或任何任务列表。 - 离开 重新排序任务键 以应用标准的 ansible-lint 键顺序,或关闭以保留原始顺序。
- 保留 验证 Ansible 结构 开启用于 play/任务结构检查(缺少
hosts,没有模块的任务,格式错误block). - 切换 显示 ansible-lint 风格提示 以提供最佳实践提示,如 FQCN 模块名称、缺少名称,以及幂等性警告。
- 复制格式化输出或将其下载为
playbook.yml.
特征
- 标准任务键顺序 -
name首先,然后是模块,然后args,loop,when,register,notify——这是 ansible-lint 所期望的顺序。 - playbook 与任务列表检测 – 当检测到 playbook 时,自动应用 play 级别的排序(
hosts,vars,pre_tasks,tasks,post_tasks,handlers)。 - 块 / 恢复 / 始终感知 – 重新排序嵌套的块式任务而不破坏其语义。
- 结构验证 – 标记缺少
hosts,没有模块的任务,格式错误的列表,以及未知的 play 级别键。 - FQCN 提示 – 建议使用
ansible.builtin.apt而非裸apt,匹配fqcn[action-core]. - 幂等性提示 – 提示当
command/shell在没有changed_when,creates, 或者removes. - 的情况下运行命令 – 检测到通过 shell 执行的包安装、systemctl 调用、git 克隆和 pip 安装,这些操作本应使用具有第一类模块。
- 遗留真值检测 – 标记应为
yes/no/on/off的值true/false(yaml[truthy]). - 过时的循环警告 – 突出显示
with_items,with_dict,以及类似项,以便您迁移到loop:. - 完全在浏览器中运行 – 没有文件上传;您的库存和密钥保留在本地。
常问问题
-
为什么 ansible-lint 会关注任务键顺序?
一致的键顺序使 playbook 更易于扫描:任务的意图(
name)首先显示,然后是执行该操作的模块,接着是其参数,最后是任何控制流(loop,when,register,notify)。当团队中的每个人遵循相同的顺序时,差异将聚焦于真正的变更,而不是外观上的调整,审查人员可以一眼识别任务模式。 -
什么是 FQCN 以及为何要为模块使用它?
FQCN 指全限定集合名称——完整的
namespace.collection.module路径,例如ansible.builtin.apt而不是仅apt。自 Ansible 2.10 将模块划分为集合以来,裸名称在多个集合提供相同短名称的模块时可能产生歧义。FQCN 使解析明确,记录每个模块的来源,并保护 playbook 免受集合顺序变更的影响。 -
何时应使用 loop: 而不是 with_items:?
这
with_*基于 lookup 的循环最初是迭代的方式,但它们将迭代与 lookup 插件耦合,限制了可组合性。关键字(自 2.5 版本引入)可直接接受任何列表,并与loop:配合良好,用于索引、标签和暂停。对于简单的列表迭代,始终优先使用loop_control;仅在尚未有干净loop:等价项的少数模式下才使用with_*。loop为什么 YAML 'yes' 在 Ansible 中被视为过时? -
YAML 1.1 将
视为布尔值。YAML 1.2 将布尔值限制为仅
yes,no,on,off,true,并且false。为了保持向前兼容性和明确性——特别是当 YAML 值被 Ansible 之外的工具消费时——ansible-lint 的true/false规则建议始终使用yaml[truthy]。使用严格的布尔值也避免了当需要字面字符串作为数据时的意外情况。true且false为什么要在 command/shell 任务中声明 changed_when?yesAnsible 通过检查模块返回数据来判断任务是否更改了系统。模块本身无法自行判断这一点——它们将任何成功执行视为变更,这使得幂等性检查失效。声明 -
(或使用
)可编码真实的变更条件:特定退出码、输出模式或文件标记。结果是,幂等性 playbook 变得更安静且更易于通过差异检查。
command,shell,并且raw于 2026 年 6 月 8 日添加changed_when在此粘贴您的 playbook.yml、角色或任务列表creates/removesAnsible Playbook YAML 格式化工具 1
