跳转到内容
安装

安装

用一条命令安装 Volant,了解控制节点和主机各自需要什么,以及如何保持更新。

终端窗口
curl -fsSL https://volant.sh/install.sh | sh

这个脚本支持 Linux 和 macOS,架构为 x86_64 和 arm64。在 Linux 上它使用静态构建。它需要 curl、tar,以及 sha256sum 或 shasum,Linux 上还需要 xz。脚本会为你的机器下载最新发布版本,校验它的 SHA-256 校验和,解压到 ~/.local/share/volant 下,并把 volant 和 volant-playbook 链接到 ~/.local/bin。脚本不要求 root 权限,也不会在这两个目录之外写入任何内容。Volant 之后运行时会写入什么,列在 Volant 会在你的机器上留下什么里。运行之前,你可以先阅读这个脚本。目前还不支持 Windows,Windows 控制节点在路线图上。

你不需要安装 Ansible。第一次运行需要 Python 时,Volant 会下载自己的 Python 和 ansible-core,大约 155 MB,保存在 ~/.local/share/volant/runtime。下载时它会打印一行提示。Volant 会在你的机器上留下什么列出了它写入的全部内容。

检查是否安装成功:

终端窗口
volant --version

如果 shell 找不到 volant,请把 ~/.local/bin 加入 PATH。缺少这一项时,脚本会打印需要添加的那一行。

脚本读取四个环境变量,并接受一个选项 --shims,它的作用与 VOLANT_SHIMS=1 相同:

变量 默认值 作用
VOLANT_VERSION 最新发布版本 要安装的版本,例如 v0.1.0-alpha.10。
VOLANT_HOME ~/.local/share/volant 各版本解压到哪里。
VOLANT_BIN_DIR ~/.local/bin volant 和 volant-playbook 的链接放在哪里。
VOLANT_SHIMS 未设置 设为 1 时,同时链接 ansible-* 这些名字。见下文。
终端窗口
curl -fsSL https://volant.sh/install.sh | VOLANT_VERSION=v0.1.0-alpha.10 sh

加上 --shims 后,脚本还会把 ansible-core 的九个程序名链接到 volant,让现有的命令行继续可用:ansible、ansible-config、ansible-console、ansible-doc、ansible-galaxy、ansible-inventory、ansible-playbook、ansible-pull 和 ansible-vault。

终端窗口
curl -fsSL https://volant.sh/install.sh | sh -s -- --shims
curl -fsSL https://volant.sh/install.sh | VOLANT_SHIMS=1 sh

ansible 命令名列出了每个名字运行什么以及有哪些不同。脚本默认从不安装它们。它运行 volant shims install,对不是它创建的文件或链接不做改动,并在 PATH 中真正的 Ansible 被遮蔽或仍然排在前面时给出提示。如果某个名字无法链接,脚本会打印 some ansible-* names were not linked, see above,仍以 0 退出,因为 Volant 已经安装好了。

setup-volant action 在 workflow 中安装 Volant。它运行上面的安装脚本,因此校验同样的 SHA-256 校验和,并把 volant 链接所在的目录加入后续步骤的 PATH。它适用于 Linux 和 macOS runner。

steps:
- uses: actions/checkout@v7
- uses: lorica-labs/volant/setup-volant@main
with:
version: v0.1.0-alpha.13
shims: true
- run: ansible-playbook -i inventory.yml site.yml

uses: 接受 volant 仓库的分支、标签或提交。0.1.0-alpha.13 之后的每个版本都包含这个 action。也请固定 version,这样新版本发布不会改变 workflow 运行的内容。

输入 默认值 作用
version 最新版本 要安装的版本,例如 v0.1.0-alpha.13。
shims false 同时链接 ansible-* 名字,效果同 --shims。
runtime false 在这一步安装托管运行时,而不是等到第一次需要它的运行时再安装。
collections 空 要安装到运行时中的 collection,与 volant runtime install --collections 相同:名字可带可选的 :version,也可以是 requirements 文件,用空格或换行分隔。
python 空 设置 VOLANT_PYTHON。之后的运行使用这个解释器,从不安装运行时。

使用 runtime 或 collections 时,action 用 actions/cache 缓存运行时目录。缓存键由 runner 的系统和架构、Volant 版本、collection 列表以及其中任何 requirements 文件的内容组成,因此之后输入相同的运行会恢复运行时,而不是重新下载。

发布包里有两个可执行文件。volant 内置了它要上传到主机的 agent。agent 是在主机上运行你的 task 的小程序。除此之外没有别的需要安装,也没有别的需要放在它旁边:

文件 说明
volant 控制节点,也就是你运行的命令。
volant-playbook 同一个控制节点,换了一个读起来像 ansible-playbook 的名字。
ansible、ansible-vault 和另外七个名字 指向 volant 的可选链接,只有使用 --shims 才有。见ansible 命令名。

第一次使用时,控制节点会把 agent 写到 ~/.cache/volant/agents/<version>/,设置了 $XDG_CACHE_HOME 时则写到它下面:包括你自己这台机器用的 agent(ansible_connection=local 使用它),以及要上传到 x86_64 和 arm64 Linux 主机的 agent。之后的运行会复用它们,与控制节点内置 agent 不一致的副本会被重新写入。

每个发布版本为每个平台提供一个归档。Linux 有静态构建和 glibc 构建。macOS 只有一个构建,链接系统库。

平台 归档 链接方式 最低要求 还需要
Linux x86_64,静态 volant-x86_64-unknown-linux-musl.tar.xz 静态,不依赖 libc 任意 Linux ssh 客户端,运行 Python 模块需要 Python
Linux x86_64,glibc volant-x86_64-unknown-linux-gnu.tar.xz 动态,只依赖 glibc glibc 2.17 ssh 客户端,运行 Python 模块需要 Python
Linux arm64,静态 volant-aarch64-unknown-linux-musl.tar.xz 静态,不依赖 libc 任意 Linux ssh 客户端,运行 Python 模块需要 Python
Linux arm64,glibc volant-aarch64-unknown-linux-gnu.tar.xz 动态,只依赖 glibc glibc 2.17 ssh 客户端,运行 Python 模块需要 Python
macOS,Apple silicon volant-aarch64-apple-darwin.tar.xz 动态,只依赖系统库 macOS 11 ssh 客户端,运行 Python 模块需要 Python
macOS,Intel volant-x86_64-apple-darwin.tar.xz 动态,只依赖系统库 macOS 10.12 ssh 客户端,运行 Python 模块需要 Python

两个 Linux 构建运行的是同一份代码,带有同样的 agent。静态构建可以在任何发行版上运行,包括 Alpine 和没有 libc 的容器。glibc 构建需要 glibc 2.17 或更新版本,覆盖 Debian 8、Ubuntu 14.04、RHEL 和 CentOS 7 以及之后的所有版本,并且能获得系统 libc 的安全更新。

安装脚本在 Linux 上始终使用静态构建。volant-installer.sh 在 glibc 2.17 或更新版本上使用 glibc 构建,在其他 Linux 上使用静态构建。cargo binstall 在任何 glibc 主机上使用 glibc 构建,在 Alpine 上使用静态构建。在低于 2.17 的 glibc 主机上,请手动下载静态归档。

静态构建不需要镜像提供任何东西,所以它可以运行在用 FROM scratch 构建的容器里:

FROM scratch
COPY volant /volant
ENTRYPOINT ["/volant"]

scratch 镜像里没有 ssh、没有 Python、没有 shell,也没有 /etc/passwd。镜像里只有控制节点时,playbook 可以使用 connection: local,并以 argv 的方式使用 command。SSH 连接需要镜像里有 ssh 客户端,Python 模块和收集 facts 需要 Python,shell 和 raw 需要 shell。控制节点会把解出的 agent 保存在 ~/.cache/volant 下,设置了 $XDG_CACHE_HOME 时则保存在它下面:请给它一个可写的目录。

  • Linux 或 macOS。
  • PATH 上有 OpenSSH 客户端。Volant 自己运行 ssh,所以你的 ~/.ssh/config 会生效。
  • 第一次有 playbook 需要 Python 时,需要 curl 或 wget,以及 tar。
  • 如果要使用安装脚本或手动解压发布包,需要 curl、tar、sha256sum 或 shasum,Linux 上还需要 xz。

对于在 Python 中运行的模块,Volant 使用带有 ansible-core 的 Python 3。找不到时,它会下载自己的一份(大约 155 MB),按固定的哈希校验每个文件,并保存在 ~/.local/share/volant/runtime 下。发生这种情况的那次运行会打印一行提示。如果你已经有这样的 Python,Volant 可以使用它:运行使用哪个解释器给出了查找顺序。另见托管运行时。

Volant 为 ansible-core 的每个程序都提供了一个命令,安装脚本可以把 ansible-* 这些名字链接到它们。ansible 命令名说明哪些在 Volant 中运行,哪些从托管运行时运行 ansible-core 自己的工具。

如果一个 playbook 只包含 command、shell、raw 和在控制节点上运行的模块,并且设置了 gather_facts: false,那它完全不需要 Python。

再运行一次安装命令。它会在你已有的版本旁边安装最新版本,并把链接指向它。旧版本仍然保留在 ~/.local/share/volant 下,所以要回退,设置 VOLANT_VERSION 即可。

终端窗口
# Only pre-releases exist so far, so name the version.
cargo binstall volant@0.1.0-alpha.10

这会下载一个已包含 agent 的发布版二进制文件。在 glibc 主机上是 glibc 构建,在 Alpine 上是静态构建。

删除发布目录、链接和控制节点的缓存。在每台主机上,agent 缓存是运行所用的每个账户各一个目录。你的项目里没有其他任何改动,所以回到 ansible-playbook不需要别的操作:

终端窗口
volant runtime remove --all
volant shims remove
rm -rf ~/.local/share/volant ~/.local/bin/volant ~/.local/bin/volant-playbook ~/.cache/volant
ssh web1 'rm -rf ~/.ansible/tmp/volant-*'