Skip to content

Collections#

Collections are the way that re-usable content is shared/delivered (plugins, roles, etc). The Free source for getting and sharing collections is Galaxy and the Paid for version is Automation Hub. The notes here are specifically focused on collections as used within AWX/Tower and will not cover local environments. Note, somewhere in ansible 2.9 the transition was made to support collections, and fully integrated in 2.10, so make sure your local ansible is 2.10+ to test locally

  • Intro video From redhat on the introduction and why.
  • Basic User Guide How to use collections
  • Developer Guide How to create collections
  • Execution Environments (EE) AWX/Tower is run in kubernetes and EE are the pods that get spun up to run the playbooks. %99 of the time the default EE is fine. In rare special cases an alternative EE can be created, however this must be managed (tech debt) so should be avoided. For this reason, many of the notes on using collections are not applicable as you do not have direct access.

Using Collections#

Using collections is very straight forward.

Declare collections to be used#

  1. Create a requirements.yml file in a collections folder at the root of the repo with your ansible playbooks. File details
  2. ./collections/requirements.yml
  3. Add the list of collections
    Text Only
    collections:
  - name: namespace_name.collection_name
    Example:
    Text Only
    collections:
  - name: community.general
  - name: umn_devex.devex_awxuser
    version: 1.0.2

Call roles in playbook#

When including a rule, make sure to use the FNC (fully namespaced collection) namespace_name.collection_name.role

In the example playbook, 'add_awx_user' is a role inside the 'umn_devex.devex_awxuser' collection:

Text Only
---
- name: Deploy awx_user and Public Key to servers
  hosts: all
  ...

  tasks:
  - name: add awx user
    include_role:
      name: umn_devex.devex_awxuser.add_awx_user

Creating Collections#

While not strictly necessary for collections in general, it is for our use case.

Prerequisites:

  • You have a Galaxy account. They are free and leverage your Github.com account.
    • If you don't already have one, go to the Galaxy site, click on the "Login" icon, this should take you to a page with the github logo, click on it and you will be directed to the github.com login page
    • The default namespace will be your github Id, but you can request an additional namespace here

There are two ways to get started. First is to use this template repo to get started, see the READ.md for details. The second options is to create it manually. The template repo contains a useful GitHub Action file you may want to grab even if you create the collection manually.

Manual: Make sure you have the latest version of ansible installed (2.10+ ideal)

  1. initialize your collection
    1. bash> ansible-galaxy collection init namespace_name.collection_name
    2. example: bash> ansible-galaxy collection init tjsobeck.example
  2. Create meta/runtime.yml and add requires_ansible: ">=2.10,<2.15" # adjust ansible versions as needed
  3. Update the galaxy.yml file
    1. set namespace: to the namespace of your galaxy account
    2. set name: to the name of this collection
    3. Fill out the rest of the values as need, but the two above are critical.
  4. Build the collection
    1. bash> ansible-galaxy collection build <path_to_collection>
    2. This will create a tar.gz file
  5. Publish the collection to ansible galaxy
    1. Make sure you have your galaxy api key
    2. bash> ansible-galaxy collection publish --api-key <api_key> <path_to_tar.gz>