volant adhoc
在每台匹配模式的主机上运行一个模块,选项和输出与 ansible 一致。
volant adhoc 就是 ansible:它在每台匹配模式的主机上运行一个模块。
volant adhoc <PATTERN> [-m MODULE] [-a ARGS] [-i INV] [-e VARS] [-l SUBSET] [-f N] [-u USER] [-c CONN] [-T SECS] [-b --become-user --become-method -K --become-password-file] [-k --connection-password-file] [--private-key --ssh-common-args --ssh-extra-args] [-J --vault-id --vault-password-file] [-M PATH] [--list-hosts] [--flush-cache] [--playbook-dir DIR] [-C] [-D] [-o] [-t DIR] [-B SECONDS] [-P SECONDS] [--task-timeout SECONDS] [--version] [-v]要运行的模块。默认:command。
模块的参数:key=value 形式的词,或者当值以 { 开头、以 } 结尾时的 JSON 对象。对于 command、shell、raw 和 script,不属于模块选项的词组成命令行。参数会用每台主机的变量和 -e 作为模板渲染。以 { 开头、以 } 结尾但不是有效 JSON 的值,会使命令以退出码 250 停止;引号未闭合则以退出码 4 停止。
以 check 模式运行任务。无法检查的模块报告 SKIPPED。
在结果之前打印任务对文件和模板所做的差异。与 -C 一起使用时,文件不会被修改。
每台主机打印一行,与 ansible 的 oneline callback 的做法相同。ansible-core 2.19.12 已弃用此选项,并在标准错误输出给出警告;见下文。
同时把每台主机的结果写入 DIR 中以主机命名的文件,与 ansible 的 tree callback 的做法相同。ansible-core 2.19.12 已弃用此选项,并在标准错误输出给出警告;见下文。
把模块作为异步作业运行,它有这么多秒来完成,并对其轮询。结果带有 ansible_job_id、started、finished 和 results_file,Origin: 字典的 async_val 就是这个值。没有 -B 时,-P 被忽略。
两次查看 -B 作业之间的秒数。默认:15。为 0 时只启动作业,结果带有 "finished": false。Origin: 字典的 poll 就是这个值。
让运行超过这么多秒的任务失败,退出码为 2,消息为 Task failed: Timed out after N second(s).。0 表示没有限制,大于 100000000 的值会使任务以 Timeout N is invalid, it must be between 0 and 100000000. 失败。Origin: 字典的 timeout 就是这个值。
打印 ansible [core 2.19.12]、配置文件、模块搜索路径、collection 位置和可执行文件位置,然后停止。可执行文件位置跟随 argv[0]:相对的 argv[0],或用 exec -a 设置的 argv[0],可能指向与实际运行的文件不同的文件。当 Volant 找到带 ansible-core 的解释器时,后面会接上模块位置以及 Python、Jinja 和 PyYAML 的版本,沿用参考实现的行。没有时这些行会省略:--version 不安装任何东西。搜索路径读取环境变量和默认值,而不是 ansible.cfg 里的 library 或 collections_path。
打印模式匹配到的主机,先是 hosts (2):,然后每台主机一行 名称,并且不运行任何东西。退出码为 0。
从 DIR 读取 group_vars/、host_vars/、相对路径和角色,并把 playbook_dir 设为它,相当于 playbook 本该提供的目录。默认值:当前工作目录。
其余选项的含义与 volant playbook 相同,包括 --flush-cache 和 -M。-f 1 一次运行一台主机,按 inventory 的顺序。
匹配不到任何主机的模式会在标准错误输出 [WARNING]: Could not match supplied host pattern, ignoring: PATTERN 和 [WARNING]: No hosts matched, nothing to do,退出码为 0。-l 没有留下任何主机时,会输出 [ERROR]: Specified inventory, host pattern and/or --limit leaves us with no hosts to target.,退出码为 1,是否带 --list-hosts 都一样。只有 -l 的模式本身匹配不到任何主机时,前面才会多一条无法匹配该模式的警告。完全没有主机的 inventory 只警告一次,不运行任何东西。没有 inventory 时,隐式的 localhost 是唯一存在的主机,只有点名它的模式才能匹配。不带 -a 运行 command、shell 或 raw 会以 [ERROR]: No argument passed to command module 和退出码 5 停止。
用法错误的退出码为 2。标准错误先输出 ansible 的 usage: 块,再输出 ansible: error: 和原因。缺少模式,或 -f 不是数字时,后面还会跟 ansible 的完整帮助;-f 小于 1 时则没有。
每台主机打印一个结果,与 ansible 的 minimal callback 的打印方式一致。command、shell 或 raw 的结果是 h1 | CHANGED | rc=0 >>,然后是它的 stdout、stderr 和 msg,之间不加任何内容。其他任何结果是 h1 | SUCCESS => ,后面跟着 JSON 形式的结果,缩进四个空格,键已排序。状态有 SUCCESS、CHANGED、FAILED(命令形式)、FAILED!(JSON 形式)、SKIPPED 和 UNREACHABLE!。在失败或不可达的结果之前,标准输出会带有 playbook 打印的同一个 [ERROR] 块。它的 Origin: 是 <adhoc 'MODULE' task>,后面是 ansible 所展示的任务,截断到 120 个字符。
当每台主机都成功或被跳过时,退出码为 0;有主机失败时为 2;有主机无法到达时为 4,不论是否同时有失败的主机。只有在 bin_ansible_callbacks 打开(ANSIBLE_LOAD_CALLBACK_PLUGINS=true)且它指定 default 以外的 callback 时,ANSIBLE_STDOUT_CALLBACK 才会改变输出:这时 oneline 的打印方式与 -o 相同,Volant 没有的名字会让命令以 Could not load 停止。-o 优先。设置 ANSIBLE_CALLBACK_RESULT_FORMAT=yaml,或在 ansible.cfg 的 [defaults] 下设置 callback_result_format = yaml 时,JSON 形式的结果改为以 YAML 打印,位于 => 之后的行中,缩进四个空格。含换行的字符串会变成字面量块。其他任何值(包括空值)都会使命令以退出码 5 停止。
每台主机一行
Section titled “每台主机一行”使用 -o 时,command、shell 或 raw 的结果是 h1 | CHANGED | rc=0 | (stdout) hi,其中的换行写作 \n,有 stderr 时后面跟 (stderr) text。其他任何结果是 h1 | SUCCESS => 加上单行 JSON 形式的结果,键已排序,用 , 分隔,逗号后没有空格。要求缩进形式的结果(例如 debug),或 -vvv 下的任何结果,保留其四个空格,但去掉换行。失败的主机打印同样两种行,使用 FAILED;对命令来说,先是命令形式,然后是 FAILED! 行。失败带有异常时,先有一行 An exception occurred during task execution. To see the full traceback, use -vvv. The error was: ...;在 -vvv 下它包含完整文本。无法到达的主机打印 h1 | UNREACHABLE!: 和它的消息。-o 不打印 [ERROR] 块、结果自带的警告和 diff,也不读取 callback_result_format。退出码与不使用它时相同。
使用 -t DIR 时输出不变。DIR 在第一个结果到达时创建,~ 会被展开,相对路径从工作目录开始。每个不是跳过的结果都以单行 JSON 写入 DIR/HOST,键已排序,末尾没有换行,覆盖该主机上一个结果留下的内容;无法到达的主机也会得到一个文件。debug 的结果以及 -vvv 下的任何结果以缩进形式写入。文件是被替换而不是原地写入:放在其位置上的链接会被替换,权限为 0600。不是单个普通文件名的主机名(空、.、.. 或含有 /)会打印 [WARNING] 且不会得到文件,而 ansible-core 会写到名字所指的任何位置,包括 ../x 和绝对路径。无法创建的目录或无法写入的文件会打印 [WARNING],运行继续。DIR 中的 $,或 ~ 后面跟用户名,会使命令以退出码 4 停止,并说明尚不支持。
两个选项都会在第一个结果之前于标准错误输出打印这些行,顺序如下:说明如何关闭弃用警告的 [WARNING],每个选项一条 [DEPRECATION WARNING],拼写和顺序与命令行给出的一致(同一组短选项中的 -o 和 -t 算作两个),主机模式的警告,然后是 oneline callback 的一条 [DEPRECATION WARNING] 和 tree callback 的一条。在 callback 加载之前就结束的运行(--list-hosts,或没有留下任何主机的 -l)只打印前两组。deprecation_warnings = False 或 ANSIBLE_DEPRECATION_WARNINGS=false 会让它们全部静默。在 -vv 下,-o 会撇开 minimal,默认输出则撇开 oneline;在 -vvvv 下,-t 会为 tree callback 增加一行。
不是模块的动作
Section titled “不是模块的动作”set_fact 像任何模块结果一样打印它的 ansible_facts。meta 带 noop、flush_handlers、clear_facts、refresh_inventory、reset_connection 或 end_host 时不打印任何内容,退出码为 0;带 end_play 时以 Unexpected Exception, this is probably a bug: 0 和退出码 250 停止,与参考实现相同,但不打印其 traceback。与 ansible-core 2.19.12 相比,这些差异仍然存在:
meta带未知动作,或没有-a时,与参考实现一样以退出码 1 停止,但它的[ERROR]块末尾没有参考实现打印的那个空行,而且没有-a时对参数的称呼不同。- 无法加载其 role 或文件的
include_role或include_tasks,其[ERROR]措辞不同。退出码一致:这两个是 2,import_role和import_tasks是 1。 group_by报告SUCCESS且"changed": false,而参考实现报告CHANGED。
-vv 以 --version 打印的块开头,然后是 Using PATH as config file(或 No config file found; using defaults),以及 Skipping callback 'default', as we already have a stdout callback. 和 Skipping callback 'oneline', as we already have a stdout callback. 这两行(使用 -o 时是 minimal 而不是 oneline)。-vvv 及以上会加上 inventory 插件的行和 volant playbook 打印的行;参考实现自己的 ESTABLISH LOCAL CONNECTION 和 EXEC 行描述的是它的模块上传,Volant 并不这样做,所以不会打印。
负的 -B、-P 或 --task-timeout,以及 -C 与 -B 同时使用,都会使命令以退出码 4 停止,并说明哪些暂不支持。-B、-P 和 --task-timeout 接受整数;其他任何值都是用法错误。