Using collections¶
Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. You can install and use collections through Ansible Galaxy.
Installing collections¶
Installing collections with ansible-galaxy
¶
You can use the ansible-galaxy collection install
command to install a collection on your system.
Note
By default, ansible-galaxy
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>
See Collection structure for details on the collection directory structure.
Installing an older version of a collection¶
By default ansible-galaxy
installs the latest collection that is available but you can add a version range
identifier to install a specific version.
To install the 1.0.0 version of the collection:
ansible-galaxy collection install my_namespace.my_collection:1.0.0
To install the 1.0.0-beta.1 version of the collection:
ansible-galaxy collection install my_namespace.my_collection:==1.0.0-beta.1
To install the collections that are greater than or equal to 1.0.0 or less than 2.0.0:
ansible-galaxy collection install my_namespace.my_collection:>=1.0.0,<2.0.0
You can specify multiple range identifiers which are split by ,
. You can use the following range identifiers:
*
: Any version, this is the default used when no range specified is set.!=
: Version is not equal to the one specified.==
: Version must be the one specified.>=
: Version is greater than or equal to the one specified.>
: Version is greater than the one specified.<=
: Version is less than or equal to the one specified.<
: Version is less than the one specified.
Note
The ansible-galaxy
command ignores any pre-release versions unless the ==
range identifier is used to
explicitly set to that pre-release version.
Install multiple collections with a requirements file¶
You can also setup a requirements.yml
file to install multiple collections in one command. This file is a YAML file in the format:
---
collections:
# With just the collection name
- my_namespace.my_collection
# With the collection name, version, and source options
- name: my_namespace.my_other_collection
version: 'version range identifiers (default: ``*``)'
source: 'The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)'
The version
key can take in the same range identifier format documented above.
Roles can also be specified and placed under the roles
key. The values follow the same format as a requirements
file used in older Ansible releases.
---
roles:
# Install a role from Ansible Galaxy.
- name: geerlingguy.java
version: 1.9.6
collections:
# Install a collection from Ansible Galaxy.
- name: geerlingguy.php_roles
version: 0.9.3
source: https://galaxy.ansible.com
Note
While both roles and collections can be specified in one requirements file, they need to be installed separately.
The ansible-galaxy role install -r requirements.yml
will only install roles and
ansible-galaxy collection install -r requirements.yml -p ./
will only install collections.
Configuring the ansible-galaxy
client¶
By default, ansible-galaxy
uses https://galaxy.ansible.com as the Galaxy server (as listed in the ansible.cfg
file under GALAXY_SERVER).
You can configure this to use other servers (such as Red Hat Automation Hub or a custom Galaxy server) as follows:
Set the server list in the GALAXY_SERVER_LIST configuration option in The configuration file.
Use the
--server
command line argument to limit to an individual server.
To configure a Galaxy server list in ansible.cfg
:
Add the
server_list
option under the[galaxy]
section to one or more server names.Create a new section for each server name.
Set the
url
option for each server name.
For Automation Hub, you additionally need to:
Set the
auth_url
option for each server name.Set the API token for each server name. Go to https://cloud.redhat.com/ansible/automation-hub/token/ and click :Get API token from the version dropdown to copy your API token.
The following example shows how to configure multiple servers:
[galaxy]
server_list = automation_hub, my_org_hub, release_galaxy, test_galaxy
[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=my_ah_token
[galaxy_server.my_org_hub]
url=https://automation.my_org/
username=my_user
password=my_pass
[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
token=my_token
[galaxy_server.test_galaxy]
url=https://galaxy-dev.ansible.com/
token=my_test_token
Note
You can use the --server
command line argument to select an explicit Galaxy server in the server_list
and
the value of this argument should match the name of the server. To use a server not in the server list, set the value to the URL to access that server (all servers in the server list will be ignored). Also the --api-key
argument is not applied to any of the predefined servers. It is only applied
if no server list is defined or a URL was specified by --server
.
Galaxy server list configuration options
The GALAXY_SERVER_LIST option is a list of server identifiers in a prioritized order. When searching for a
collection, the install process will search in that order, e.g. automation_hub
first, then my_org_hub
, release_galaxy
, and
finally test_galaxy
until the collection is found. The actual Galaxy instance is then defined under the section
[galaxy_server.{{ id }}]
where {{ id }}
is the server identifier defined in the list. This section can then
define the following keys:
url
: The URL of the galaxy instance to connect to, this is required.token
: A token key to use for authentication against the Galaxy instance, this is mutually exclusive withusername
username
: The username to use for basic authentication against the Galaxy instance, this is mutually exclusive withtoken
password
: The password to use for basic authenticationauth_url
: The URL of a Keycloak server ‘token_endpoint’ if using SSO auth (Automation Hub for ex). This is mutually exclusive withusername
.auth_url
requirestoken
.
As well as being defined in the ansible.cfg
file, these server options can be defined as an environment variable.
The environment variable is in the form ANSIBLE_GALAXY_SERVER_{{ id }}_{{ key }}
where {{ id }}
is the upper
case form of the server identifier and {{ key }}
is the key to define. For example I can define token
for
release_galaxy
by setting ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=secret_token
.
For operations where only one Galaxy server is used, i.e. publish
, info
, login
then the first entry in the
server_list
is used unless an explicit server was passed in as a command line argument.
Note
Once a collection is found, any of its requirements are only searched within the same Galaxy instance as the parent collection. The install process will not search for a collection requirement in a different Galaxy instance.
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 }}'
To avoid a lot of typing, you can use the collections
keyword added in Ansible 2.8:
- 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 }}'
This keyword creates a ‘search path’ for non namespaced plugin references. It does not import roles or anything else. Notice that you still need the FQCN for non-action or module plugins.
See also
- Developing collections
Develop or modify a collection.
- Collection Galaxy metadata structure
Understand the collections metadata structure.
- Mailing List
The development mailing list
- irc.freenode.net
#ansible IRC chat channel