Distributing collections

You can distribute your collections by publishing them on a distribution server. Distribution servers include Ansible Galaxy, Red Hat Automation Hub, and privately hosted Automation Hub instances. You can publish any collection to Ansible Galaxy and/or to a privately hosted Automation Hub instance. If your collection is certified by Red Hat, you can publish it to the Red Hat Automation Hub.

Distributing collections involves three major steps: #. Configuring your distribution server(s) #. Building your collection artifact #. Publishing your collection

Configuring your distribution server or servers

  1. Get a namespace on each distribution server you want to use (Galaxy, private Automation Hub, Red Hat Automation Hub).

  2. Get an API token for each distribution server you want to use.

  3. Specify the API token for each distribution server you want to use.

Getting a namespace

You need a namespace on Galaxy and/or Automation Hub to upload your collection. To get a namespace:

Getting your API token

You need an API token for Galaxy and/or Automation Hub to upload your collection. Use the API token(s) to authenticate your connection to the distribution server(s) and protect your content.

To get your API token:

Specifying your API token

Once you have retrieved your API token, you can specify the correct token for each distribution server in two ways:

  • Pass the token to the ansible-galaxy command using the --token.

  • Configure the token within a Galaxy server list in your ansible.cfg file.

Specifying your API token with the --token argument

You can use the --token argument with the ansible-galaxy command (in conjunction with the --server argument or GALAXY_SERVER setting in your ansible.cfg file). You cannot use apt-key with any servers defined in your Galaxy server list.

ansible-galaxy collection publish ./geerlingguy-collection-1.2.3.tar.gz --token=<key goes here>

Specifying your API token with a Galaxy server list

You can configure one or more distribution servers for Galaxy in your ansible.cfg file under the galaxy_server_list section. For each server, you also configure the token.

[galaxy]
server_list = release_galaxy

[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
token=my_token

See Configuring the ansible-galaxy client for complete details.

Building a collection tarball

Once you have configured one or more distribution servers, you must build a collection tarball. To build a collection, run ansible-galaxy collection build from inside the root directory of the collection:

collection_dir#> ansible-galaxy collection build

This creates a tarball of the built collection in the current directory which can be uploaded to your distribution server:

my_collection/
├── galaxy.yml
├── ...
├── my_namespace-my_collection-1.0.0.tar.gz
└── ...

Note

  • Certain files and folders are excluded when building the collection artifact. See Ignoring files and folders to exclude other files you would not want to distribute.

  • If you used the now-deprecated Mazer tool for any of your collections, delete any and all files it added to your releases/ directory before you build your collection with ansible-galaxy.

  • The current Galaxy maximum tarball size is 2 MB.

This tarball is mainly intended to upload to Galaxy as a distribution method, but you can use it directly to install the collection on target systems.

Ignoring files and folders

By default the build step will include all the files in the collection directory in the final build artifact except for the following:

  • galaxy.yml

  • *.pyc

  • *.retry

  • tests/output

  • previously built artifacts in the root directory

  • various version control directories like .git/

To exclude other files and folders when building the collection, you can set a list of file glob-like patterns in the build_ignore key in the collection’s galaxy.yml file. These patterns use the following special characters for wildcard matching:

  • *: Matches everything

  • ?: Matches any single character

  • [seq]: Matches and character in seq

  • [!seq]:Matches any character not in seq

For example, if you wanted to exclude the sensitive folder within the playbooks folder as well any .tar.gz archives you can set the following in your galaxy.yml file:

build_ignore:
- playbooks/sensitive
- '*.tar.gz'

Note

This feature is only supported when running ansible-galaxy collection build with Ansible 2.10 or newer.

Collection versions

Each time you publish your collection, you create a new version. Once you publish a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before publishing. The only way to change a collection is to release a new version. The latest version of a collection (by highest version number) will be the version displayed everywhere in Galaxy or Automation Hub; however, users will still be able to download older versions.

Collection versions use Semantic Versioning for version numbers. Please read the official documentation for details and examples. In summary:

  • Increment major (for example: x in x.y.z) version number for an incompatible API change.

  • Increment minor (for example: y in x.y.z) version number for new functionality in a backwards compatible manner (for example new modules/plugins, parameters, return values).

  • Increment patch (for example: z in x.y.z) version number for backwards compatible bug fixes.

Trying collections locally

Before you publish your collection, test it out locally. Every time you publish a tarball, you create a new version of your collection. Testing the collection locally gives you confidence that the new version will contain the functionality you want without unexpected behavior.

Trying your collection from the tarball

You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to access the collection:

ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections

You should use one of the values configured in COLLECTIONS_PATHS for your path. This is also where Ansible itself will expect to find collections when attempting to use them. If you don’t specify a path value, ansible-galaxy collection install installs the collection in the first path defined in COLLECTIONS_PATHS, which by default is ~/.ansible/collections.

If you want to use a collection directly out of a checked out git repository, see Contributing to collections.

Next, try using the local collection inside a playbook. For examples and more details see Using collections

Trying your collection from a git repository

You can also test a version of your collection in development by installing it from a git repository.

ansible-galaxy collection install git+https://github.com/org/repo.git,devel

You can install a collection in a git repository by providing the URI to the repository instead of a collection name or path to a tar.gz file. The collection must contain a galaxy.yml or MANIFEST.json file, which will be used to generate the would-be collection artifact data from the directory. The URI should be prefixed with git+ (or with git@ to use a private repository with ssh authentication) and optionally supports a comma-separated git commit-ish version (for example, a commit or tag).

Warning

Embedding credentials into a git URI is not secure. Make sure to use safe auth options for security reasons. For example, use SSH, netrc or http.extraHeader/url.<base>.pushInsteadOf in Git config to prevent your creds from being exposed in logs.

# Install a collection in a repository using the latest commit on the branch 'devel'
ansible-galaxy collection install git+https://github.com/organization/repo_name.git,devel

# Install a collection from a private github repository
ansible-galaxy collection install [email protected]:organization/repo_name.git

# Install a collection from a local git repository
ansible-galaxy collection install git+file:///home/user/path/to/repo/.git

In a requirements.yml file, you can also use the type and version keys in addition to using the git+repo,version syntax for the collection name.

collections:
  - name: https://github.com/organization/repo_name.git
    type: git
    version: devel

Git repositories can be used for collection dependencies as well. This can be helpful for local development and testing but built/published artifacts should only have dependencies on other artifacts.

dependencies: {'[email protected]:organization/repo_name.git': 'devel'}

Default repository search locations

There are two paths searched in a repository for collections by default.

The first is the galaxy.yml or MANIFEST.json file in the top level of the repository path. If the file exists it’s used as the collection metadata and the individual collection will be installed.

├── galaxy.yml
├── plugins/
│   ├── lookup/
│   ├── modules/
│   └── module_utils/
└─── README.md

The second is a galaxy.yml or MANIFEST.json file in each directory in the repository path (one level deep). In this scenario, each directory with a metadata file is installed as a collection.

directory/
├── docs/
├── MANIFEST.json
├── plugins/
│   ├── inventory/
│   └── modules/
└── roles/

Specifying the location to search for collections

If you have a different repository structure or only want to install a subset of collections, you can add a fragment to the end of your URI (before the optional comma-separated version) to indicate which path ansible-galaxy should inspect for metadata file(s). The path should be a directory to a collection or multiple collections (rather than the path to a galaxy.yml file or MANIFEST.json file).

namespace/
└── name/
    ├── docs/
    ├── galaxy.yml
    ├── plugins/
    │   ├── README.md
    │   └── modules/
    ├── README.md
    └── roles/
# Install all collections in a particular namespace
ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/

# Install an individual collection using a specific commit
ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/name/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5

Publishing a collection

Once you have a namespace and an API token for each distribution server you want to use, and you have created and tested a collection tarball, you can distribute your collection by publishing the tarball to Ansible Galaxy, Red Hat Automation Hub, or a privately hosted Automation Hub instance. You can use either the ansible-galaxy collection publish command or the distribution server (Galaxy, Automation Hub) itself.

Each time you add features or make changes to your collection, you must create a new collection artifact and publish a new version of the collection. For details on versioning, see Collection versions.

Publish a collection using ansible-galaxy

Note

By default, ansible-galaxy uses https://galaxy.ansible.com as the Galaxy server (as listed in the ansible.cfg file under GALAXY_SERVER). If you are only publishing your collection to Ansible Galaxy, you do not need any further configuration. If you are using Red Hat Automation Hub or any other Galaxy server, see Configuring the ansible-galaxy client.

To upload the collection artifact with the ansible-galaxy command:

ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz

Note

The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See Getting your API token for details.

The ansible-galaxy collection publish command triggers an import process, just as if you uploaded the collection through the Galaxy website. The command waits until the import process completes before reporting the status back. If you want to continue without waiting for the import result, use the --no-wait argument and manually look at the import progress in your My Imports page.

Alternately, you can publish to Galaxy without configuring the token in ansible.cfg. Use the --token argument directly on the command line.

ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz --token abcdefghijklmnopqrtuvwxyz

Note

Using the --token argument is not recommended because passing secrets on the command line may lead to exposing them to others on the system

Publishing a collection using the Galaxy website

To publish your collection directly on the Galaxy website:

  1. Go to the My Content page, and click the Add Content button on one of your namespaces.

  2. From the Add Content dialogue, click Upload New Collection, and select the collection archive file from your local filesystem.

When you upload a collection, it always uploads to the namespace specified in the collection metadata in the galaxy.yml file, no matter which namespace you select on the website. If you are not an owner of the namespace specified in your collection metadata, the upload request will fail.

Once Galaxy uploads and accepts a collection, you will be redirected to the My Imports page, which displays output from the import process, including any errors or warnings about the metadata and content contained in the collection.

See also

Using collections

Learn how to install and use collections.

Mailing List

The development mailing list

irc.libera.chat

#ansible IRC chat channel