Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. As modules move from the core Ansible repository into collections, the module documentation will move to the collections pages.
You can install and use collections through Ansible Galaxy.
For details on how to develop collections see Developing collections.
For the current development status of Collections and FAQ see Ansible Collections Community Guide.
Installing collections
Installing collections with ansible-galaxy
By default, ansible-galaxy collection install uses https://galaxy.ansible.com as the Galaxy server (as listed in the ansible.cfg file under GALAXY_SERVER). You do not need any further configuration.
See Configuring the ansible-galaxy client if you are using any other Galaxy server, such as Red Hat Automation Hub.
To install a collection hosted in Galaxy:
ansible-galaxy collection install my_namespace.my_collection
You can also directly use the tarball from your build:
ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections
Note
The install command automatically appends the path ansible_collections to the one specified with the -p option unless the parent directory is already in a folder called ansible_collections.
When using the -p option to specify the install path, use one of the values configured in COLLECTIONS_PATHS, as this is where Ansible itself will expect to find collections. If you don’t specify a path, ansible-galaxy collection install installs the collection to the first path defined in COLLECTIONS_PATHS, which by default is ~/.ansible/collections
You can also keep a collection adjacent to the current playbook, under a collections/ansible_collections/ directory structure.
./
├── play.yml
├── collections/
│ └── ansible_collections/
│ └── my_namespace/
│ └── my_collection/<collection structure lives here>Installing a collection from a git repository
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 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 git@github.com: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: {'git@github.com: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 file in the top level of the repository path. If the galaxy.yml 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 file in each directory in the repository path (one level deep). In this scenario, each directory with a galaxy.yml is installed as a collection.
directory/
├── docs/
├── galaxy.yml
├── 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 galaxy.yml file(s). The path should be a directory to a collection or multiple collections (rather than the path to a galaxy.yml 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
Lab
Step i: Install amazon.aws collection, Boto
connect to your awx server using mobaxterm and enter
pip3 install boto3
ansible-galaxy collection install amazon.aws
IF YOU SEE ERRORS LIKE BELOW
- downloading role 'collection', owned by
[WARNING]: - collection was NOT installed successfully: Content has no field named 'owner'
ERROR! - you can use --ignore-errors to skip failed roles and finish processing the list.
sudo apt remove ansible
sudo add-apt-repository ppa:ansible/ansible-2.9
sudo apt install ansible
sudo ansible-galaxy collection install amazon.aws
Step ii: Specify your collection path in the ansible config file
vi /etc/ansible/ansible.cfg
Insert the below line
collections_paths = /home/ubuntu/.ansible/collections/ansible_collections
Save
