volant galaxy
The options of ansible-galaxy, checked by Volant itself, while its subcommands are made native one at a time.
volant galaxy takes the subcommands and options of ansible-galaxy from ansible-core 2.19.12, so scripts and CI jobs written for it keep their command lines. It is being rewritten in Volant, without the Python runtime. Today it parses the options and makes the checks ansible-galaxy makes first, then refuses the subcommand until its native version lands.
volant galaxy collection <download|init|build|publish|install|list|verify> [OPTIONS]volant galaxy role <init|remove|delete|list|search|import|setup|info|install> [OPTIONS]Every subcommand takes -s/--server, --token/--api-key, -c/--ignore-certs, --timeout and -v, which can be repeated. collection download and collection install also take --clear-response-cache and --no-cache. An unknown option, or a value of the wrong kind, exits with 2 and prints the usage. volant galaxy --version prints the version block of ansible-galaxy.
The first checks
Section titled “The first checks”These come before any work, with the messages and exit codes of ansible-galaxy:
| Case | Message | Exit |
|---|---|---|
collection install with names and -r |
[ERROR]: The positional collection_name arg and --requirements-file are mutually exclusive. |
1 |
collection install or download with neither |
[ERROR]: You must specify a collection name or a requirements file. |
1 |
-r names a file that does not exist |
[ERROR]: The requirements file '<path>' does not exist. |
1 |
role install with no name and no -r |
[ERROR]: - you must specify a user/role name or a roles file |
5 |
role install -r with a file not ending in .yml or .yaml |
[ERROR]: Invalid role requirements file, it must end with a .yml or .yaml extension |
1 |
role list with no roles path that exists |
[WARNING]: - the configured path <path> does not exist. for each path, then [ERROR]: - None of the provided paths were usable. Please specify a valid path with --roles-path |
5 |
When no configured collections path lies under the PATH of collection install -p PATH, the command prints the warning of ansible-galaxy first: [WARNING]: The specified collections path '<PATH>' is not part of the configured Ansible collections paths '<paths>'. The installed collection will not be picked up in an Ansible run, unless within a playbook-adjacent collections directory. The runtime’s own collections/ directory, which Volant adds last to the collections path, is left out of <paths>.
Installing from a tarball
Section titled “Installing from a tarball”collection install installs a collection tarball natively: volant galaxy collection install acme-demo-1.0.0.tar.gz -p DIR. The name and version come from the tarball’s MANIFEST.json, not from the file name. The collection goes under DIR/ansible_collections/<namespace>/<name>, or under the first collections path without -p. Only the files FILES.json lists are written, each checked against its SHA-256 first. A file is 0644, or 0755 when the archive marks it executable. An entry that would land outside the collection is refused, and so is a link that points outside it. A failed install leaves no half-written collection behind. The output, the messages and the exit codes are those of ansible-galaxy. A collection already installed at the same version gives Nothing to do. All requested collections are already installed. If you want to reinstall them, consider using –force., and --force installs it again over the old tree. When PATH/ansible_collections already exists, the -p warning reads that the path appears to be part of the pip Ansible package, as ansible-galaxy says it.
collection install also takes a git repository: git+<url>, with ,<ref> for a branch, a tag or a commit, HEAD by default, and #/<subdir> for a collection that is not at the repository’s root, as in git+https://host/org/repo.git,v1.0.0 or git+file:///work/mono/.git#/collections/demo. In a requirements file it is an entry with type: git, its version being the ref. Volant runs the system git: a shallow clone for HEAD, a full one with a checkout otherwise, then installs the checkout as a source tree. A repository with no collection at its root installs every collection in its immediate subdirectories. A collection that depends on a git+ URL has that repository cloned too, unless --no-deps is given. What comes from a repository has no version to compare, so it is installed again on every run. A version that is not SemVer stops the install with Invalid version found for the collection, exit 1. git’s own messages reach the terminal, as they do under ansible-galaxy. A password in the URL is replaced by ******** in every message. Without git on PATH, the command fails with Could not find git executable to extract the collection from the Git repository, exit 1.
URLs to tarballs, namespace directories and signatures are refused until they are native: [ERROR]: volant galaxy collection install from a URL or a namespace directory is not supported yet, or with signatures, exit 1.
Creating a collection
Section titled “Creating a collection”collection init <namespace>.<name> [--init-path DIR] [--collection-skeleton DIR] [-e VARS] [-f] writes a new collection under DIR/<namespace>/<name>, ./ by default, and prints - Collection <namespace>.<name> was created successfully. Without a skeleton it writes the default skeleton of ansible-core 2.19.12: galaxy.yml, README.md, meta/runtime.yml, plugins/README.md and the empty docs/ and roles/ directories. --collection-skeleton, or GALAXY_COLLECTION_SKELETON, names a skeleton directory to copy instead. Its .j2 files are rendered with --extra-vars and lose the extension, except under playbooks/*/templates and roles/*/templates. Its links stay links, and what GALAXY_COLLECTION_SKELETON_IGNORE matches is left out. An existing collection directory is an error unless -f is given, which empties it first. The messages and exit codes are those of ansible-galaxy.
Building a collection
Section titled “Building a collection”collection build [PATH] [--output-path DIR] [-f] turns a source tree with a galaxy.yml, . by default, into <namespace>-<name>-<version>.tar.gz under DIR, ./ by default, and prints Created collection for <namespace>.<name> at <path>. galaxy.yml needs namespace, name, version, readme and authors; a missing key, or a missing galaxy.yml, fails with the message of ansible-galaxy. The tarball holds MANIFEST.json, FILES.json and the tree, without what ansible-galaxy leaves out: galaxy.yml, .git and the other version control directories, __pycache__, *.pyc, *.retry, tests/output, earlier artifacts of the collection, and what build_ignore lists. A file is 0644, or 0755 when its owner may run it; a link inside the tree stays a link, and one to a directory outside it is skipped with a warning. An existing artifact is an error unless -f is given. Volant writes every time as 0 and every owner as root, so building the same tree twice gives the same bytes; ansible-galaxy stamps the current time. A galaxy.yml with a manifest: key is refused for now.
collection install DIR installs a source tree the same way, without a tarball, and prints Created collection for <namespace>.<name>:<version> at <path> between its Installing and installed successfully lines. collection download builds a source tree into the download folder.
Installing from Galaxy servers
Section titled “Installing from Galaxy servers”collection install also takes names, with a range when wanted: demo.base, demo.base:1.0.0, "demo.base:>=1.0.0,<2.0.0", and the entries of -r. Each name is resolved against the servers with its dependencies, each at the highest version that meets every range asked of it, backtracking when two ranges clash. Pre-releases count only with --pre or when named exactly. Every tarball is downloaded, checked against the SHA-256 the server gives, and unpacked as above. A collection installed from a server also gets ansible_collections/<namespace>.<name>-<version>.info/GALAXY.yml, which records where it came from. A collection already installed at a version that fits is kept: '<name>:<version>' is already installed, skipping.
-n skips the dependencies, -U moves installed collections to the newest version in range, -f reinstalls the requested collections and --force-with-deps their dependencies too, -i goes on after a failed install with a warning, and --offline asks no server. When no set of versions meets every range, the command fails with the message of ansible-galaxy, which lists the ranges and ends with a hint about --pre; the Python objects ansible-galaxy prints after that hint are left out.
Downloading for an offline install
Section titled “Downloading for an offline install”collection download resolves the collections asked for with their dependencies, as install does, and saves each tarball in the folder -p names, ./collections by default. It then writes a requirements.yml there listing the tarballs by file name, with their versions. On a machine with no network, volant galaxy collection install --offline -r requirements.yml run from that folder installs them without asking any server. The file names are read from the working directory, as ansible-galaxy reads them. -n leaves the dependencies out, and -r and --pre work as for install. Under --offline, a name that no tarball provides, or a dependency that is not installed, fails with the resolver’s message.
Listing and verifying collections
Section titled “Listing and verifying collections”collection list [NAME] [-p PATH]... [--format human|json|yaml] prints, for each directory of -p and of the collections path that holds collections, a # <path>/ansible_collections block with each collection’s name and version, the version being * when the collection has no MANIFEST.json. The columns are as wide as the longest name and version, as ansible-galaxy pads them. --format json prints {"<path>": {"<namespace>.<name>": {"version": "<version>"}}} on one line, and --format yaml the same as YAML. A -p that does not exist is warned about; when no path can be read, the command fails with exit 5. ansible-galaxy also lists the collection ansible-core keeps inside its own Python package, ansible._protomatter; Volant, which has no such package, does not.
collection verify NAME... [-p PATH] [--offline] checks each installed collection: MANIFEST.json, then FILES.json against the hash the manifest gives, then every file against its own, then the tree for files and directories FILES.json does not list, *.pyc aside. Each difference is listed under Collection <name> contains modified content in the following files:, and the command exits 1. Without --offline, the server’s tarball of the same version is downloaded and its MANIFEST.json is the reference; with it, the installed one is. A collection that is not installed, or that has no MANIFEST.json, is an error; -i turns errors into warnings.
Installing and managing roles
Section titled “Installing and managing roles”role install NAME... [-p PATH] [-r FILE] installs each role into the first roles path: -p, or the first configured one. A name is owner.role[,version[,name]], looked up through the first server’s API v1; without a version, the highest one the server lists is taken, then the repository’s branch, then master. A path to a tarball, a URL and a git+ source install too; a tarball or a git source takes its role name from the third field of the line, or from the path when that field is empty. The archive’s top directory is dropped, and meta/.galaxy_install_info records the version and the install date. A role already installed at the same version is skipped; at another version, it is warned about and kept, unless --force replaces it. The dependencies of meta/main.yml and meta/requirements.yml follow, unless -n is given; --force-with-deps replaces those already installed. A role that fails is warned about, and the command exits 1 unless -i lets it go on. -g keeps the .git directory of a git role.
role list [NAME] [-p PATH] prints each roles path as # <path>, then - <role>, <version> for each role it holds, (unknown version) when the role has no install information. role remove NAME... [-p PATH] deletes each role from the first roles path, - <role> is not installed, skipping. for a directory that holds no role.
Galaxy servers
Section titled “Galaxy servers”The servers come from -s, else from [galaxy] server_list and the [galaxy_server.<name>] sections of ansible.cfg, else from GALAXY_SERVER, https://galaxy.ansible.com by default. Every ANSIBLE_GALAXY_* variable comes before the file. Each server takes url, token, validate_certs and timeout. --token beats the file’s token, -c turns certificate checks off, and --timeout sets how long to wait, 60 seconds by default. A server that cannot be reached is skipped with the warning of ansible-galaxy, and the next one is asked.
The token is sent as Authorization: Token <token> and never printed. Without one, the token file is read, GALAXY_TOKEN_PATH, by default <ANSIBLE_HOME>/galaxy_token, created empty with mode 0600 when missing. Proxies come from https_proxy, http_proxy, all_proxy and no_proxy; unlike ansible-galaxy, which picks the variable by the URL’s scheme, the first of them that is set applies to every URL. Answers are kept for a day in <ANSIBLE_HOME>/galaxy_cache/api.json, the same file ansible-galaxy uses. --no-cache leaves it aside and --clear-response-cache empties it. username, password and auth_url are not read.
Requirements files
Section titled “Requirements files”-r reads the requirements file as ansible-galaxy does: collections: and roles: in one file, or the old bare list of roles, which only role install accepts. An include: entry brings the roles of another file, named from the working directory. When -r is given twice, the last one counts. When the file has no entry for the command, collection install and role install print Skipping install, no requirements found and exit 0. -vvv prints Reading requirement file at '<path>' first. A malformed file fails with the message of ansible-galaxy, exit 1: no entries, keys other than collections and roles, a role entry with neither name nor src, a collection name that is not namespace.name and points at nothing, or an unknown type. A collection entry’s source names the server it is installed from, by its name in the server list or by URL; another URL is asked as a server of its own. A source that is neither fails with Collections requirement 'source' entry should contain a valid Galaxy API URL but it does not: <source> is not an HTTP URL.
Verbose output
Section titled “Verbose output”-v is counted after the subcommand, as ansible-galaxy counts it; ansible-galaxy ignores a -v written before the subcommand, and Volant counts it.
| Level | What is added |
|---|---|
-v |
Using <path> as config file, or No config file found; using defaults. |
-vv |
Before that line, the block --version prints: ansible-galaxy [core <version>], config file, configured module search path, ansible collection location, executable location. The Python, Jinja and PyYAML lines come only when the controller’s interpreter answers, as for volant adhoc. |
-vvv |
Reading requirement file at '<file>', found role <dict> in yaml file, Processing role <name> , Found installed collection <name>:<version> at '<path>', Created <token file> or Opened <token file>, Collection '<name>:<version>' obtained from server <server> <url>, Remote collection cached as '<path>', Skipping '<path>' for collection build. |
-vvvv |
Validating downloaded file hash. The other HTTP lines of ansible-galaxy (Calling Galaxy at, Found API version, the response cache) are not printed. |
ansible-galaxy also reports ansible._protomatter, the collection ansible-core keeps inside its own Python package; Volant has no such package and never reports it. role remove asks the default Galaxy server for its API before it deletes anything, which prints Opened <token file> at -vvv; Volant removes the role without contacting a server.
Refused subcommands
Section titled “Refused subcommands”A subcommand that is not native yet fails with [ERROR]: volant galaxy <subcommand> is not supported yet, exit 1. collection publish and role delete, search, import, setup and info need a Galaxy account or the server’s role database, and stay refused: [ERROR]: volant galaxy <subcommand> is not supported, exit 1.
volant runtime install --collections still installs collections with the runtime’s own ansible-galaxy.