# 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`
  - Installing an older version of a collection
  - Install multiple collections with a requirements file
  - Configuring the `ansible-galaxy` client
- Using collections in a Playbook

## 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`:

1. Add the `server_list` option under the `[galaxy]` section to one or more server names.
2. Create a new section for each server name.
3. Set the `url` option for each server name.

For Automation Hub, you additionally need to:

1. Set the `auth_url` option for each server name.
2. 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 with `username`
- `username`: The username to use for basic authentication against the Galaxy instance, this is mutually exclusive with `token`
- `password`: The password to use for basic authentication
- `auth_url`: The URL of a Keycloak server ‘token_endpoint’ if using SSO auth (Automation Hub for ex). This is mutually exclusive with `username`. `auth_url` requires `token`.

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