跳转到内容
安装

volant shadow

在不连接任何主机的情况下重放 ansible-playbook 记录的一次运行,看看 Volant 会有哪些不同的做法。

volant shadow replay 读取 volant.compat.record 回调写下的记录(参见运行记录)。它在 Volant 中以相同的选项运行相同的 playbook,对每个本会连到主机的任务,都用 ansible-core 记录的结果作答。然后它把 Volant 的决定与 ansible-core 的实际行为进行比较。不连接任何主机,也不启动任何 agent。无风险切换介绍了完整流程,包括 CI。

终端窗口
volant shadow replay RECORDING [--json] [--ledger PATH]
volant shadow status [--json] [--require-ready] [--ledger PATH]

以 JSON Lines 输出报告:每个差异一个对象,最后是一个汇总对象。

要追加或读取的记录簿,代替当前生效的 ansible.cfg 旁边的 .volant/shadow.jsonl(没有 ansible.cfg 时位于工作目录)。

除非记录簿中每个 playbook 都是 ready,否则以 1 退出。

记录中写明了运行读取过的文件。每个文件都从记录的工作目录出发查找,因此请在仓库中相同的位置运行重放。出现以下情况时,重放拒绝开始,退出码为 4:

  • 记录的格式比当前 Volant 能读取的更新;消息会写明两个版本;
  • 某个 playbook 或清单文件与记录中的不同(site.yml changed since the recording);
  • 某个 -e @文件 参数指向的文件发生了变化。

对 2.19 系列之外的 ansible-core 的记录,重放时会给出 out-of-profile 警告。被中断的运行留下的不完整记录,会重放到其最后一个完整行,主机也会在记录结束处停下。

运行的选项来自记录:清单、extra 变量、tags、limit、check 和 diff 模式、权限提升、vault id 以及 forks。无需再次提供。

本会连到主机的任务,改为得到记录中的结果。之后由 Volant 自己应用 changed_when、failed_when、register、循环和 until。until 会按顺序得到记录中失败的尝试。pause 采用其提示当时得到的回答,并且不会等待。记录为不可达的主机在重放中也不可达。在控制端运行的任务,例如 debug、set_fact、include 和 meta,照常由 Volant 计算。

带有 Python 模块或收集 facts 的 playbook,仍需要控制端上的 ansible-core 来准备它们,可通过 VOLANT_PYTHON 或托管运行时提供。

有些值每次运行都不同:pipe、env、password、lines 和 url lookup,名称中含有 random 的任何 lookup,指向重放所在目录之外的 file lookup,now(),以及 random 和 shuffle 过滤器。在重放中,它们改为给出一个未知值。从记录的 no_log 结果中读取的任何键也是如此,因为记录只保留了它的状态。

读取了未知值的表达式整体都是未知的,无论它对这个值做了什么:周围的文本、过滤器、比较、属性或元素。未知的任务参数不做比较,报告会把它计入 unknown: 加原因,例如 unknown: lookup 'pipe'。读取了未知值的 when、loop、changed_when、failed_when 或 until 会按记录行事:任务像当时一样运行或被跳过,遍历记录中的元素,保留记录中的状态,并在记录停止的那次尝试处停止。

重放的运行输出到 stderr,与 volant playbook 完全一样。报告输出到 stdout。报告开头是汇总:比较了多少个任务、涉及多少台主机,以及按类型统计的差异。然后列出哪些内容未比较及原因,再列出每个差异:主机、文件:行号、任务名、ansible-core 的做法、Volant 的做法以及两者的区别:

Shadow replay: 23 tasks compared on 2 hosts, 1 divergence: judgment 1.
Arguments not compared: no_log 2, not in the recording 8.
judgment local site.yml:30 fails
ansible: {"status":"ok"}
volant: {"status":"failed"}
diff: status: "ok" -> "failed"

差异分为五种,按严重程度从高到低:

类型 检测的内容
inventory 缺少某台主机,或主机所属的组与记录中不同。
flow 一个引擎运行了而另一个没有运行的任务、不同的顺序,或只在一侧运行的 handler。
loop 元素数量不同,或元素的值不同。
args Volant 发给模块的某个参数,其值与模块实际运行时的值不同。只出现在记录中的参数是模块的默认值,不做比较。
judgment 状态不同(ok、changed、failed、skipped)、跳过任务的条件不同、尝试次数不同,或最终汇总不同。

某台主机出现第一个 flow 差异后,该主机余下的部分不再比较,因为之后的每个任务都已错位。其他主机继续比较。no_log 任务只比较其状态,因为记录中没有保留它的其他内容。

使用 --json 时,每个差异占一行:

{"host":"local","task":{"path":"site.yml:30","name":"fails"},"kind":"judgment","ansible":{"status":"ok"},"volant":{"status":"failed"},"diff":"status: \"ok\" -> \"failed\""}

最后一行是汇总:

{"summary":{"compared":23,"hosts":2,"divergences":{"judgment":1},"not_compared":{"no_log":2},"arguments_not_compared":{"no_log":2,"not_recorded":8},"truncated":false}}

not_compared 中的原因有 after_flow(该主机出现 flow 差异之后)、no_log(只比较状态)以及 unknown: <原因>(未知的循环元素)。arguments_not_compared 中的原因有 no_log、not_recorded(ansible-core 没有把 invocation 传给回调,例如 debug,或 ansible-core 2.21 对所有任务都是如此)controller(Volant 在控制端运行了该任务,没有发送任何内容)以及按参数计数的 unknown: <原因>。

一次干净的重放说明不了太多。每次未被拒绝的重放都会向记录簿追加一行,即当前生效的 ansible.cfg 旁边的 .volant/shadow.jsonl:日期、playbook 及其哈希、Volant 版本、记录的 ansible-core 及其哈希、存在时 volant.lock 的哈希、本次运行的 --limit 和 --tags、主机数、比较过和未比较的任务、每个比较过的任务以及重放编译出的每个任务的 文件:行号、按类型统计的差异,以及 clean、dirty 或 out-of-profile。Volant 不决定记录簿在两次运行之间存放在哪里:可以把它纳入版本控制,也可以放在 CI 缓存中。

volant shadow status 读取记录簿,并为每个 playbook 给出一行:

  • 连续次数是连续 clean 重放的次数。一次 dirty 重放会将其清零,新的 Volant 版本也会。playbook 或 collection 的修改不会清零,因为两个引擎运行的是同样的文件。out-of-profile 重放不计入。
  • 覆盖率是该 playbook 的任务(包括所有分支)中,被这段连续重放至少比较过一次的比例。从未比较过的任务按名称列出。
  • 当连续次数达到 shadow_runs(默认 5)且覆盖率达到 shadow_coverage(默认 0.9)时,结论为 ready;这两个值都从 ansible.cfg 的 [volant] 小节读取。最后一次重放为 dirty 时结论为 diverged,否则为 not-ready,并给出原因。
site.yml not-ready streak 2/5, coverage 96% of 25 tasks (1 never compared), no divergence
2 clean replays in a row, 5 wanted

使用 --json 时,每行是一个对象,包含 playbook、verdict、streak、coverage、tasks、never_compared、last_divergence 和 reasons。无法读取的记录簿行会被跳过,并给出写明其行号的警告。

退出码 含义
0 没有差异。
1 至少有一个差异。
4 无法在当前仓库中重放该记录:格式更新,或有文件发生了变化。

volant shadow status 以 0 退出;在 --require-ready 下,若有 playbook 不是 ready 或记录簿为空,则以 1 退出。