Ansible Galaxy and Collections
Relevant source files
The following files were used as context for generating this wiki page:
- lib/ansible/cli/galaxy.py
- lib/ansible/galaxy/collection/concrete_artifact_manager.py
- lib/ansible/galaxy/data/collections_galaxy_meta.yml
- test/units/cli/test_galaxy.py
- test/integration/targets/ansible-galaxy-collection/tasks/download.yml
- lib/ansible/cli/doc.py
- lib/ansible/galaxy/data/default/role/README.md
- test/integration/targets/ansible-galaxy-collection-cli/files/expected_full_manifest.txt
Ansible Galaxy is a system for managing and distributing Ansible content, primarily in the form of Roles and Collections. The ansible-galaxy command-line interface (CLI) is the primary tool for interacting with this system, allowing users to initialize, build, publish, install, and manage Ansible content. Collections are the modern format for packaging and distributing Ansible content, including roles, modules, plugins, and playbooks.
The GalaxyCLI class is the main entry point for all ansible-galaxy operations. It parses user commands and arguments, and dispatches them to the appropriate execution functions for either roles or collections. It interacts with a GalaxyAPI for server-side operations and a ConcreteArtifactsManager for handling local and remote collection artifacts.
Sources: lib/ansible/cli/galaxy.py:120-136, lib/ansible/cli/galaxy.py:408-444
Core Components
The Ansible Galaxy functionality is built upon several key classes that manage CLI interactions, API communication, and artifact handling.
This diagram shows the main classes involved in the ansible-galaxy command and their relationships.
Sources: lib/ansible/cli/galaxy.py, lib/ansible/galaxy/collection/concrete_artifact_manager.py
GalaxyCLI
The GalaxyCLI class in lib/ansible/cli/galaxy.py is the main controller for the ansible-galaxy command. It is responsible for:
- Argument Parsing: It defines and parses all command-line arguments and subcommands for both roles and collections using
init_parser. - Action Dispatching: Based on the parsed arguments, it calls the corresponding
execute_*method (e.g.,execute_install,execute_build). - Backward Compatibility: It implicitly handles the
rolesubcommand for older command formats where the type was not specified. - API Server Management: It initializes and manages connections to one or more Galaxy API servers, handling configuration from
ansible.cfgand command-line options.
Sources: lib/ansible/cli/galaxy.py:120-136, lib/ansible/cli/galaxy.py:171-405, lib/ansible/cli/galaxy.py:408-444
ConcreteArtifactsManager
The ConcreteArtifactsManager class in lib/ansible/galaxy/collection/concrete_artifact_manager.py is responsible for handling collection artifacts. Its key functions include:
- Downloading: It fetches remote collections from Galaxy-compatible servers, direct URLs to tarballs, or SCM repositories.
- Caching: It maintains a cache of downloaded artifacts and their metadata to avoid redundant downloads.
- Metadata Extraction: It can extract metadata (
galaxy.ymlcontent) from both tarball artifacts (.tar.gz) and local source directories. - Temporary Directory Management: It manages a temporary working directory for storing downloaded and unpacked artifacts.
Sources: lib/ansible/galaxy/collection/concrete_artifact_manager.py:40-62
Collection Management
Collections are the primary way to distribute Ansible content. The ansible-galaxy collection command provides a suite of tools to manage them.
Collection Structure and Metadata
A collection is a standardized directory structure. At its root, it must contain a galaxy.yml file that defines the collection's metadata.
This diagram illustrates a typical Ansible Collection directory structure.
Sources: test/units/cli/test_galaxy.py:658-662, test/integration/targets/ansible-galaxy-collection-cli/files/expected_full_manifest.txt
galaxy.yml Metadata
The galaxy.yml file is a YAML file containing metadata about the collection. The structure and available keys are defined in lib/ansible/galaxy/data/collections_galaxy_meta.yml.
| Key | Required | Type | Description |
|---|---|---|---|
namespace | Yes | str | The namespace of the collection (e.g., company, organization). |
name | Yes | str | The name of the collection. |
version | Yes | str | The collection version, must be Semantic Versioning compatible. |
readme | Yes | str | Path to the collection's README file (Markdown). |
authors | Yes | list | A list of the collection's authors. |
description | No | str | A short summary of the collection. |
license | No | list | A list of SPDX license identifiers. Mutually exclusive with license_file. |
license_file | No | str | Path to the license file. Mutually exclusive with license. |
tags | No | list | A list of tags for searching and indexing. |
dependencies | No | dict | A dictionary of other collections this collection depends on. |
repository | No | str | URL of the SCM repository. |
documentation | No | str | URL to online documentation. |
homepage | No | str | URL to the project's homepage. |
issues | No | str | URL to the issue tracker. |
build_ignore | No | list | A list of fnmatch patterns to exclude files from the build artifact. |
manifest | No | sentinel | A dict to control MANIFEST.in style directives for building the artifact. |
Sources: lib/ansible/galaxy/data/collections_galaxy_meta.yml:1-90
ansible-galaxy collection Commands
The GalaxyCLI class implements several subcommands for managing collections.
| Command | Description |
|---|---|
init | Initialize a new collection with a skeleton structure. |
build | Build a collection artifact (.tar.gz) from a source directory. |
publish | Publish a collection artifact to a Galaxy server. |
install | Install one or more collections from a Galaxy server, URL, or local file. |
list | List installed collections. |
download | Download collection artifacts and their dependencies for offline installation. |
verify | Verify the integrity and signatures of installed collections. |
Sources: lib/ansible/cli/galaxy.py:192-205
install Command
The install command is one of the most common operations. It handles fetching and installing collections and their dependencies.
The process flow for installing a collection is as follows:
This diagram shows the sequence of events when a user installs a collection.
Key install options:
-r, --requirements-file: Install collections from arequirements.ymlfile.-p, --collections-path: Specify the directory to install collections into.--no-deps: Do not install dependencies.--force: Force overwrite of an existing collection.--disable-gpg-verify: Disable GPG signature verification.
Sources: lib/ansible/cli/galaxy.py:302-364, lib/ansible/cli/galaxy.py:1071-1133
build Command
The build command packages a collection source directory into a distributable tarball artifact. The artifact contains the collection content along with two metadata files: MANIFEST.json and FILES.json.
MANIFEST.json: Contains the collection's metadata (fromgalaxy.yml) and a manifest of all files in the artifact.FILES.json: A detailed list of all files and directories, including their type (file/dir) and a SHA256 checksum for files.
This diagram shows the process of building a collection artifact.
Sources: lib/ansible/cli/galaxy.py:366-381, test/units/cli/test_galaxy.py:848-936
download Command
The download command is used to fetch collection artifacts and their dependencies for offline use. It creates a collections subdirectory and a requirements.yml file that can be used with ansible-galaxy collection install -r requirements.yml --offline.
Example usage from an integration test:
- name: download collection with multiple dependencies
command: ansible-galaxy collection download parent_dep.parent_collection:1.0.0 -s galaxy_ng {{ galaxy_verbosity }}
register: download_collection
args:
chdir: '{{ galaxy_dir }}/download'
This command downloads parent_dep.parent_collection and its dependencies, placing the tarballs and a requirements.yml in the {{ galaxy_dir }}/download/collections directory.
Sources: lib/ansible/cli/galaxy.py:207-223, test/integration/targets/ansible-galaxy-collection/tasks/download.yml:5-11
Role Management
While collections are the modern approach, ansible-galaxy still fully supports managing standalone roles.
ansible-galaxy role Commands
The ansible-galaxy role subcommand (or the implicit role command) provides actions for roles.
| Command | Description |
|---|---|
init | Initialize a new role with a default skeleton. |
install | Install roles from Galaxy, a URL, or a local tar file. |
remove | Delete roles from the local roles_path. |
list | List installed roles. |
info | View details about a specific role. |
import | Import a role from a GitHub repository into a Galaxy server. |
delete | Remove a role from a Galaxy server. |
search | Search for roles on a Galaxy server. |
Sources: lib/ansible/cli/galaxy.py:200-205, lib/ansible/cli/galaxy.py:225-300
Role Skeleton
The ansible-galaxy role init <role_name> command creates a directory structure for a new role. This structure includes standard directories like tasks, handlers, defaults, vars, meta, and templates. A default README.md is also created.
# lib/ansible/galaxy/data/default/role/README.md
Role Name
=========
A brief description of the role goes here.
Requirements
------------
Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here...
Role Variables
--------------
A description of the settable variables for this role should go here...
Dependencies
------------
A list of other roles hosted on Galaxy should go here...
Example Playbook
----------------
...
License
-------
BSD
Author Information
------------------
...
This is the content of the default README file created for a new role.
Sources: lib/ansible/galaxy/data/default/role/README.md, lib/ansible/cli/galaxy.py:225-247
Conclusion
The ansible-galaxy CLI is a powerful and versatile tool for managing Ansible content. It provides a comprehensive set of commands for both modern Collections and legacy Roles, covering the entire lifecycle from creation and building to distribution and installation. The system is designed to interact with Galaxy servers for centralized sharing while also supporting offline workflows, direct SCM integration, and local file-based management. Key components like GalaxyCLI, GalaxyAPI, and ConcreteArtifactsManager work together to provide a robust and flexible content management experience for Ansible users.
Sources: lib/ansible/cli/galaxy.py, lib/ansible/galaxy/collection/concrete_artifact_manager.py