Using collections
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
note:
If you install a collection manually as described in this paragraph, the collection will not be upgraded automatically when you upgrade the ``ansible`` package or ``ansible-core``.
Installing collections with ansible-galaxy
Installing an older version of a collection
Installing a collection from a git repository
Install multiple collections with a requirements file
Downloading a collection for offline use
Configuring the ansible-galaxy client
Downloading collections
To download a collection and its dependencies for an offline install, run ansible-galaxy collection download. This
downloads the collections specified and their dependencies to the specified folder and creates a requirements.yml
file which can be used to install those collections on a host without access to a Galaxy server. All the collections
are downloaded by default to the ./collections folder.
Just like the install command, the collections are sourced based on the
configured galaxy server config. Even if a collection to download was specified by a URL
or path to a tarball, the collection will be redownloaded from the configured Galaxy server.
Collections can be specified as one or multiple collections or with a requirements.yml file just like
ansible-galaxy collection install.
To download a single collection and its dependencies:
ansible-galaxy collection download my_namespace.my_collection
To download a single collection at a specific version:
ansible-galaxy collection download my_namespace.my_collection:1.0.0
To download multiple collections either specify multiple collections as command line arguments as shown above or use a requirements file in the format documented with collection_requirements_file.
ansible-galaxy collection download -r requirements.yml
You can also download a source collection directory. The collection is built with the mandatory galaxy.yml file.
ansible-galaxy collection download /path/to/collection
ansible-galaxy collection download git+file:///path/to/collection/.git
You can download multiple source collections from a single namespace by providing the path to the namespace.
ns/
├── collection1/
│ ├── galaxy.yml
│ └── plugins/
└── collection2/
├── galaxy.yml
└── plugins/
ansible-galaxy collection install /path/to/ns
All the collections are downloaded by default to the ./collections folder but you can use -p or
--download-path to specify another path:
ansible-galaxy collection download my_namespace.my_collection -p ~/offline-collections
Once you have downloaded the collections, the folder contains the collections specified, their dependencies, and a
requirements.yml file. You can use this folder as is with ansible-galaxy collection install to install the
collections on a host without access to a Galaxy or Automation Hub server.
# This must be run from the folder that contains the offline collections and requirements.yml file downloaded
# by the internet-connected host
cd ~/offline-collections
ansible-galaxy collection install -r requirements.yml
Listing collections
To list installed collections, run ansible-galaxy collection list. This shows all of the installed collections found in the configured collections search paths. It will also show collections under development which contain a galaxy.yml file instead of a MANIFEST.json. The path where the collections are located are displayed as well as version information. If no version information is available, a * is displayed for the version number.
# /home/astark/.ansible/collections/ansible_collections
Collection Version
-------------------------- -------
cisco.aci 0.0.5
cisco.mso 0.0.4
sandwiches.ham *
splunk.es 0.0.5
# /usr/share/ansible/collections/ansible_collections
Collection Version
----------------- -------
fortinet.fortios 1.0.6
pureport.pureport 0.0.8
sensu.sensu_go 1.3.0
Run with -vvv to display more detailed information.
To list a specific collection, pass a valid fully qualified collection name (FQCN) to the command ansible-galaxy collection list. All instances of the collection will be listed.
> ansible-galaxy collection list fortinet.fortios
# /home/astark/.ansible/collections/ansible_collections
Collection Version
---------------- -------
fortinet.fortios 1.0.1
# /usr/share/ansible/collections/ansible_collections
Collection Version
---------------- -------
fortinet.fortios 1.0.6
To search other paths for collections, use the -p option. Specify multiple search paths by separating them with a :. The list of paths specified on the command line will be added to the beginning of the configured collections search paths.
> ansible-galaxy collection list -p '/opt/ansible/collections:/etc/ansible/collections'
# /opt/ansible/collections/ansible_collections
Collection Version
--------------- -------
sandwiches.club 1.7.2
# /etc/ansible/collections/ansible_collections
Collection Version
-------------- -------
sandwiches.pbj 1.2.0
# /home/astark/.ansible/collections/ansible_collections
Collection Version
-------------------------- -------
cisco.aci 0.0.5
cisco.mso 0.0.4
fortinet.fortios 1.0.1
sandwiches.ham *
splunk.es 0.0.5
# /usr/share/ansible/collections/ansible_collections
Collection Version
----------------- -------
fortinet.fortios 1.0.6
pureport.pureport 0.0.8
sensu.sensu_go 1.3.0
Verifying collections
Verifying collections with ansible-galaxy
Once installed, you can verify that the content of the installed collection matches the content of the collection on the server. This feature expects that the collection is installed in one of the configured collection paths and that the collection exists on one of the configured galaxy servers.
ansible-galaxy collection verify my_namespace.my_collection
The output of the ansible-galaxy collection verify command is quiet if it is successful. If a collection has been modified, the altered files are listed under the collection name.
ansible-galaxy collection verify my_namespace.my_collection
Collection my_namespace.my_collection contains modified content in the following files:
my_namespace.my_collection
plugins/inventory/my_inventory.py
plugins/modules/my_module.py
You can use the -vvv flag to display additional information, such as the version and path of the installed collection, the URL of the remote collection used for validation, and successful verification output.
ansible-galaxy collection verify my_namespace.my_collection -vvv
...
Verifying 'my_namespace.my_collection:1.0.0'.
Installed collection found at '/path/to/ansible_collections/my_namespace/my_collection/'
Remote collection found at 'https://galaxy.ansible.com/download/my_namespace-my_collection-1.0.0.tar.gz'
Successfully verified that checksums for 'my_namespace.my_collection:1.0.0' match the remote collection
If you have a pre-release or non-latest version of a collection installed you should include the specific version to verify. If the version is omitted, the installed collection is verified against the latest version available on the server.
ansible-galaxy collection verify my_namespace.my_collection:1.0.0
In addition to the namespace.collection_name:version format, you can provide the collections to verify in a requirements.yml file. Dependencies listed in requirements.yml are not included in the verify process and should be verified separately.
ansible-galaxy collection verify -r requirements.yml
Verifying against tar.gz files is not supported. If your requirements.yml contains paths to tar files or URLs for installation, you can use the --ignore-errors flag to ensure that all collections using the namespace.name format in the file are processed.
Using collections in a Playbook
Once installed, you can reference a collection content by its fully qualified collection name (FQCN):
- hosts: all
tasks:
- my_namespace.my_collection.mymodule:
option1: value
This works for roles or any type of plugin distributed within the collection:
- hosts: all
tasks:
- import_role:
name: my_namespace.my_collection.role1
- my_namespace.mycollection.mymodule:
option1: value
- debug:
msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'
Simplifying module names with the collections keyword
The collections keyword lets you define a list of collections that your role or playbook should search for unqualified module and action names. So you can use the collections keyword, then simply refer to modules and action plugins by their short-form names throughout that role or playbook.
warning::
If your playbook uses both the collections keyword and one or more roles, the roles do not inherit the collections set by the playbook. This is one of the reasons we recommend you always use FQCN. See below for roles details.
Using collections in roles
Within a role, you can control which collections Ansible searches for the tasks inside the role using the collections keyword in the role's meta/main.yml. Ansible will use the collections list defined inside the role even if the playbook that calls the role defines different collections in a separate collections keyword entry. Roles defined inside a collection always implicitly search their own collection first, so you don't need to use the collections keyword to access modules, actions, or other roles contained in the same collection.
# myrole/meta/main.yml
collections:
- my_namespace.first_collection
- my_namespace.second_collection
- other_namespace.other_collection
Using collections in playbooks
In a playbook, you can control the collections Ansible searches for modules and action plugins to execute. However, any roles you call in your playbook define their own collections search order; they do not inherit the calling playbook's settings. This is true even if the role does not define its own collections keyword.
- hosts: all
collections:
- my_namespace.my_collection
tasks:
- import_role:
name: role1
- mymodule:
option1: value
- debug:
msg: '{{ lookup("my_namespace.my_collection.lookup1", "param1")| my_namespace.my_collection.filter1 }}'
The collections keyword merely creates an ordered 'search path' for non-namespaced plugin and role references. It does not install content or otherwise change Ansible's behavior around the loading of plugins or roles. Note that an FQCN is still required for non-action or module plugins (for example, lookups, filters, tests).
Using a playbook from a collection
versionadded:: 2.11
You can also distribute playbooks in your collection and invoke them using the same semantics you use for plugins:
ansible-playbook my_namespace.my_collection.playbook1 -i ./myinventory
From inside a playbook:
- import_playbook: my_namespace.my_collection.playbookX
A few recommendations when creating such playbooks, hosts: should be generic or at least have a variable input.
- hosts: all # Use --limit or customized inventory to restrict hosts targeted
- hosts: localhost # For things you want to restrict to the controller
- hosts: '{{target|default("webservers")}}' # Assumes inventory provides a 'webservers' group, but can also use ``-e 'target=host1,host2'``
This will have an implied entry in the collections: keyword of my_namespace.my_collection just as with roles.
seealso:
developing_collections Develop or modify a collection.
collections_galaxy_meta Understand the collections metadata structure. Mailing List The development mailing list
communication_irc How to join Ansible chat channels