README
¶
cli
CLI binaries: ansible-playbook, ansible, ansible-inventory, ansible-vault, ansible-galaxy, ansible-pull, ansible-doc, ansible-config, ansible-console.
Nine of the ten console scripts real ansible-core 2.21.4 declares in its own
entry_points.txt. The tenth is ansible-test, which drives collection test
suites against collections this port does not host.
Part of go-ansible — a pure-Go (CGO=0), functional-parity port of Ansible.
All nine build for windows/amd64 and windows/arm64 as well as the six
64-bit Unix targets, so the control node can be Windows — which real
ansible-core does not support at all. Whether a target can be Windows is
a separate question: ansible_connection: winrm reaches one, but the
ansible.windows module family is not ported, so what runs over it today
is whatever needs no POSIX shell.
Docker / OCI image
Every tagged release publishes a multi-arch image bundling all nine
binaries, FROM scratch — no libc, no interpreter, nothing but the
static binaries themselves (real Ansible cannot do this: it needs
Python plus several pip-installed packages just to be the controller;
see BENCHMARKS.md
for the measured comparison).
docker run --rm -v "$PWD:/pb" ghcr.io/go-ansible/cli \
-i /pb/inventory.yml /pb/site.yml
The entrypoint is ansible-playbook; run any other binary with
--entrypoint:
docker run --rm --entrypoint ansible-doc ghcr.io/go-ansible/cli setup
Published for all six 64-bit Linux targets — linux/amd64,
linux/arm64, linux/riscv64, linux/loong64, linux/ppc64le and
linux/s390x. This paragraph used to say loong64 was excluded for want
of QEMU/binfmt setup; it is in the workflow's platform list and in the
published manifest:
$ docker manifest inspect ghcr.io/go-ansible/cli | grep architecture
amd64 arm64 loong64 ppc64le riscv64 s390x
ansible-doc names the module's own collection
A page header and a -l line carry the collection the module really comes
from, as real prints it:
$ ansible-doc rocketchat
> MODULE community.general.rocketchat
$ ansible-doc synchronize
> MODULE ansible.posix.synchronize
It printed ansible.builtin. for every module until v0.143.0, on a premise
that was true when written and wrong for 514 of the 576 registered modules.
Worth stating because it was not cosmetic: modules.NormalizeName strips any
known collection prefix, so ansible.builtin.rocketchat ran here and real
Ansible rejects it — this port's own documentation was handing out a name that
works nowhere else, and nothing local could catch that.
Known limitation: command/shell tasks against a local
connection need /bin/sh, which doesn't exist in a scratch image —
debug/copy/template/set_fact and similar work fine. A playbook
targeting a real remote host over SSH is unaffected either way, since
the shell requirement is the target's, not this image's.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ansible
command
Command ansible runs a single module against a pattern of inventory hosts (Ansible's "ad-hoc" mode).
|
Command ansible runs a single module against a pattern of inventory hosts (Ansible's "ad-hoc" mode). |
|
ansible-config
command
Command ansible-config shows go-ansible's configuration.
|
Command ansible-config shows go-ansible's configuration. |
|
ansible-console
command
Command ansible-console is an interactive REPL for running ad-hoc modules against a live-changeable host pattern — the interactive counterpart to ansible's one-shot ad-hoc mode.
|
Command ansible-console is an interactive REPL for running ad-hoc modules against a live-changeable host pattern — the interactive counterpart to ansible's one-shot ad-hoc mode. |
|
ansible-doc
command
Command ansible-doc prints documentation for go-ansible's modules.
|
Command ansible-doc prints documentation for go-ansible's modules. |
|
ansible-galaxy
command
Command ansible-galaxy installs roles from a requirements file.
|
Command ansible-galaxy installs roles from a requirements file. |
|
ansible-inventory
command
Command ansible-inventory shows the inventory as this port parsed it, in real ansible-inventory's own shapes: the --list JSON dump, the --host variable dump, and the --graph tree.
|
Command ansible-inventory shows the inventory as this port parsed it, in real ansible-inventory's own shapes: the --list JSON dump, the --host variable dump, and the --graph tree. |
|
ansible-playbook
command
Command ansible-playbook runs a playbook against an inventory.
|
Command ansible-playbook runs a playbook against an inventory. |
|
ansible-pull
command
Command ansible-pull clones (or updates) a git repository and runs a playbook from it against this machine — the pull-mode counterpart to ansible-playbook's push mode, for a target that fetches and applies its own configuration instead of being reached over SSH.
|
Command ansible-pull clones (or updates) a git repository and runs a playbook from it against this machine — the pull-mode counterpart to ansible-playbook's push mode, for a target that fetches and applies its own configuration instead of being reached over SSH. |
|
ansible-vault
command
Command ansible-vault encrypts/decrypts/views files in Ansible's Vault 1.1 format.
|
Command ansible-vault encrypts/decrypts/views files in Ansible's Vault 1.1 format. |
|
internal
|
|
|
adhoc
Package adhoc is the ad-hoc single-module-against-a-host-pattern execution logic shared by cmd/ansible and cmd/ansible-console — the same "connect, run one module on every matched host, print a host | STATUS => json line as each finishes" flow both binaries need, factored out once instead of copied.
|
Package adhoc is the ad-hoc single-module-against-a-host-pattern execution logic shared by cmd/ansible and cmd/ansible-console — the same "connect, run one module on every matched host, print a host | STATUS => json line as each finishes" flow both binaries need, factored out once instead of copied. |
|
extravars
Package extravars parses Ansible's `-e`/`--extra-vars` command-line argument: a `key=value` pair, a raw JSON/YAML object, or `@file` to load one from disk (JSON or YAML, by extension).
|
Package extravars parses Ansible's `-e`/`--extra-vars` command-line argument: a `key=value` pair, a raw JSON/YAML object, or `@file` to load one from disk (JSON or YAML, by extension). |
|
invload
Package invload loads the inventory the way real Ansible's CLI does: a source it cannot use is a WARNING and the run continues with only the implicit localhost, rather than a fatal error.
|
Package invload loads the inventory the way real Ansible's CLI does: a source it cannot use is a WARNING and the run continues with only the implicit localhost, rather than a fatal error. |
|
termcolor
Package termcolor decides whether output should carry ANSI colour, by real Ansible's rules rather than by a flag alone.
|
Package termcolor decides whether output should carry ANSI colour, by real Ansible's rules rather than by a flag alone. |
|
usage
Package usage answers a request for help the way real Ansible does.
|
Package usage answers a request for help the way real Ansible does. |
|
vaultpw
Package vaultpw resolves the vault password the way real Ansible's CLI does, so every command that accepts --vault-password-file gets the same behavior from one place rather than each growing its own copy.
|
Package vaultpw resolves the vault password the way real Ansible's CLI does, so every command that accepts --vault-password-file gets the same behavior from one place rather than each growing its own copy. |
|
verbosity
Package verbosity registers real ansible's -v family on a flag.FlagSet.
|
Package verbosity registers real ansible's -v family on a flag.FlagSet. |
|
version
Package version formats a one-line --version string shared by all four go-ansible CLI binaries.
|
Package version formats a one-line --version string shared by all four go-ansible CLI binaries. |