Installation
Install Volant with one command, check what the controller and the hosts need, and keep it up to date.
Install
Section titled “Install”curl -fsSL https://volant.sh/install.sh | shThe script works on Linux and macOS, on x86_64 and arm64. On Linux it takes the static build. It needs curl, tar and sha256sum or shasum, plus xz on Linux. It downloads the newest release for your machine, checks its SHA-256 checksum, unpacks it under ~/.local/share/volant, and links volant and volant-playbook into ~/.local/bin. The script asks for no root access and writes nothing outside those two directories. What Volant writes later, when it runs, is listed in What Volant leaves on your machines. You can read the script before you run it. Windows is not supported yet: a Windows controller is on the roadmap.
You do not need Ansible installed. On the first run that needs Python, Volant downloads its own copy of Python and ansible-core, about 155 MB, and keeps it in ~/.local/share/volant/runtime. It prints one line when it does. What Volant leaves on your machines lists everything it writes.
Check that it worked:
volant --versionIf your shell cannot find volant, add ~/.local/bin to your PATH. The script prints the line to add when it is missing.
Options
Section titled “Options”The script reads four environment variables and takes one option, --shims, which does what VOLANT_SHIMS=1 does:
| Variable | Default | What it changes |
|---|---|---|
VOLANT_VERSION |
the newest release | The release to install, such as v0.1.0-alpha.10. |
VOLANT_HOME |
~/.local/share/volant |
Where releases are unpacked. |
VOLANT_BIN_DIR |
~/.local/bin |
Where the volant and volant-playbook links go. |
VOLANT_SHIMS |
unset | Set to 1 to also link the ansible-* names. See below. |
curl -fsSL https://volant.sh/install.sh | VOLANT_VERSION=v0.1.0-alpha.10 shKeep your ansible command lines
Section titled “Keep your ansible command lines”Add --shims and the script also links the nine ansible-core program names to volant, so existing command lines keep working: ansible, ansible-config, ansible-console, ansible-doc, ansible-galaxy, ansible-inventory, ansible-playbook, ansible-pull and ansible-vault.
curl -fsSL https://volant.sh/install.sh | sh -s -- --shimscurl -fsSL https://volant.sh/install.sh | VOLANT_SHIMS=1 shAnsible command names lists what each name runs and what differs. The script never installs them by default. It runs volant shims install, which leaves a file or link it did not make alone and says when a real Ansible on your PATH is hidden or still runs first. If a name could not be linked, the script prints some ansible-* names were not linked, see above and still exits 0, because Volant is installed.
In GitHub Actions
Section titled “In GitHub Actions”The setup-volant action installs Volant in a workflow. It runs the install script above, so it checks the same SHA-256 checksum, and it adds the directory of the volant link to the PATH of the steps that follow. It works on Linux and macOS runners.
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.ymluses: takes a branch, a tag or a commit of the volant repository. The action is in every release after 0.1.0-alpha.13. Pin version as well, so a new release does not change what the workflow runs.
| Input | Default | What it does |
|---|---|---|
version |
the newest release | The release to install, such as v0.1.0-alpha.13. |
shims |
false |
Also link the ansible-* names, as --shims does. |
runtime |
false |
Install the managed runtime in this step instead of on the first run that needs it. |
collections |
empty | Collections to install into the runtime, as with volant runtime install --collections: names with an optional :version, or a requirements file, separated by spaces or new lines. |
python |
empty | Sets VOLANT_PYTHON. Runs then use that interpreter and never install the runtime. |
With runtime or collections, the action caches the runtime directory with actions/cache. The cache key is made of the runner’s system and architecture, the Volant version, the collections and the content of any requirements file among them, so a later run with the same inputs restores the runtime instead of downloading it.
What you get
Section titled “What you get”The release has two executables. volant carries the agents it uploads to your hosts. An agent is a small program that runs your tasks on a host. There is nothing else to install and nothing to keep next to it:
| File | What it is |
|---|---|
volant |
The controller, the command you run. |
volant-playbook |
The same controller under a name that reads like ansible-playbook. |
ansible, ansible-vault and the other seven names |
Optional links to volant, only with --shims. See Ansible command names. |
On first use, the controller writes its agents to ~/.cache/volant/agents/<version>/, or under $XDG_CACHE_HOME when it is set: the agent for your own machine, used by ansible_connection=local, and the ones it uploads to x86_64 and arm64 Linux hosts. Later runs reuse them, and a copy that does not match the agent built into the controller is written again.
Builds and platforms
Section titled “Builds and platforms”Every release has one archive per platform. Linux has a static build and a glibc build. macOS has one build, which links the system libraries.
| Platform | Archive | Linkage | Minimum | Needs beside it |
|---|---|---|---|---|
| Linux x86_64, static | volant-x86_64-unknown-linux-musl.tar.xz |
Static. No libc. | Any Linux | ssh client, Python for Python modules |
| Linux x86_64, glibc | volant-x86_64-unknown-linux-gnu.tar.xz |
Dynamic, glibc only | glibc 2.17 | ssh client, Python for Python modules |
| Linux arm64, static | volant-aarch64-unknown-linux-musl.tar.xz |
Static. No libc. | Any Linux | ssh client, Python for Python modules |
| Linux arm64, glibc | volant-aarch64-unknown-linux-gnu.tar.xz |
Dynamic, glibc only | glibc 2.17 | ssh client, Python for Python modules |
| macOS, Apple silicon | volant-aarch64-apple-darwin.tar.xz |
Dynamic, system libraries only | macOS 11 | ssh client, Python for Python modules |
| macOS, Intel | volant-x86_64-apple-darwin.tar.xz |
Dynamic, system libraries only | macOS 10.12 | ssh client, Python for Python modules |
Both Linux builds run the same code and carry the same agents. The static build runs on any distribution, including Alpine and a container with no libc. The glibc build needs glibc 2.17 or newer, which covers Debian 8, Ubuntu 14.04, RHEL and CentOS 7 and everything after them, and it takes the security updates of the system libc.
The install script always takes the static build on Linux. volant-installer.sh takes the glibc build on glibc 2.17 or newer and the static build on any other Linux. cargo binstall takes the glibc build on any glibc host and the static build on Alpine. On a glibc host older than 2.17, download the static archive by hand.
In a container
Section titled “In a container”The static build needs nothing from the image, so it runs in a container built FROM scratch:
FROM scratchCOPY volant /volantENTRYPOINT ["/volant"]A scratch image has no ssh, no Python, no shell and no /etc/passwd. With only the controller in it, a playbook can run on connection: local and use command with argv. SSH connections need an ssh client in the image, Python modules and fact gathering need Python, and shell and raw need a shell. The controller keeps the agent it extracts under ~/.cache/volant, or under $XDG_CACHE_HOME when it is set: give it a directory it can write.
What the machines need
Section titled “What the machines need”- Linux or macOS.
- The OpenSSH client on your
PATH. Volant runssshitself, so your~/.ssh/configapplies. curlorwget, andtar, the first time a playbook needs Python.- To use the install script or unpack a release by hand,
curl,tar,sha256sumorshasum, andxzon Linux.
For the modules that run in Python, Volant uses a Python 3 with ansible-core. When it finds none, it downloads its own (about 155 MB), checks every file against a pinned hash and keeps it under ~/.local/share/volant/runtime. A run that does this prints one line. If you already have such a Python, Volant can use it: Which interpreter a run uses gives the order. See The managed runtime.
Volant has a command for each ansible-core program, and the install script can link the ansible-* names to them. Ansible command names says which ones run in Volant and which run ansible-core’s own tool from the managed runtime.
A playbook made only of command, shell, raw and controller-side modules, with gather_facts: false, needs no Python at all.
- Linux, x86_64 or arm64.
- An SSH server and an account you can log into with a key or an ssh-agent.
- A Python 3 interpreter for Python modules and fact gathering. The host does not need ansible-core: Volant sends every file a module imports.
sudoif you usebecome.
Nothing has to be installed by hand. The controller uploads the agent with the first task and caches it under ~/.ansible/tmp.
Update
Section titled “Update”Run the install command again. It installs the newest release next to the ones you have and points the links at it. Older releases stay under ~/.local/share/volant, so going back is a matter of setting VOLANT_VERSION.
Other ways to install
Section titled “Other ways to install”# Only pre-releases exist so far, so name the version.cargo binstall volant@0.1.0-alpha.10This downloads a release binary with its agents included. On a glibc host it is the glibc build, on Alpine the static build.
Every release on the releases page has one archive per platform, named volant-<target>.tar.xz as in the table above, with a .sha256 file next to it. Unpack it (this needs xz) and put volant on your PATH:
tar -xJf volant-x86_64-unknown-linux-musl.tar.xzinstall -m 755 volant-x86_64-unknown-linux-musl/volant ~/.local/bin/volantcargo install --git https://github.com/lorica-labs/volant volantA build from source does not carry the agents, because they are cross-compiled for the hosts. Point VOLANT_AGENT_DIR at a directory that holds them, or build them from a checkout: cargo build leaves a local agent next to the controller, and just agent-musl builds the x86_64 Linux one. just smoke-embedded shows how a release build embeds them.
Uninstall
Section titled “Uninstall”Remove the release directory, the links and the controller’s caches. On each host, the agent cache is one directory per account the run acted as. Nothing else in your project changes, so going back to ansible-playbook needs nothing more:
volant runtime remove --allvolant shims removerm -rf ~/.local/share/volant ~/.local/bin/volant ~/.local/bin/volant-playbook ~/.cache/volantssh web1 'rm -rf ~/.ansible/tmp/volant-*'