ansible/docs/docsite/rst/user_guide/collections_using.rst

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

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.

developing_collections

Develop or modify a collection.

collections_galaxy_meta

Understand the collections metadata structure.

Mailing List

The development mailing list

irc.freenode.net

#ansible IRC chat channel