Home

Collections

Collections are a distribution format for Ansible content. They can be used to package and distribute playbooks, roles, modules, and plugins. You will be able to publish and use collections via Ansible's Galaxy repository.

Note

This is a Tech-Preview feature and is only supported by Ansible 2.8 (or greater). Future Galaxy or Ansible releases may introduce breaking changes.

Collection Structure

Collections follow a simple data stucture, none of the directories are required unless you have specific content that belongs in one of them. They do require a galaxy.yml at the root level of the collection. This file contains all of the metadata that Galaxy and other tools need in order to package, build and publish it.:

collection/
├── docs/
├── galaxy.yml
├── plugins/
│   ├── modules/
│   │   └── module1.py
│   ├── inventory/
│   └── .../
├── README.md
├── roles/
│   ├── role1/
│   ├── role2/
│   └── .../
├── playbooks/
│   ├── files/
│   ├── vars/
│   ├── templates/
│   └── tasks/
└── tests/

Note

• We will only accept .yml extensions for galaxy.yml.
• A full structure can be found at Draft collection
• Not all directories are currently in use, those are placeholders for future features

galaxy.yml

This file contains the information about a colleciton neccessary for Ansible tools to operate. galaxy.yml has the following fields (subject to expansion):

namespace: "namespace_name"
name: "collection_name"
version: "1.0.12"
authors:
    - "Author1"
    - "Author2 (http://author2.example.com)"
    - "Author3 <author3@example.com>"
dependencies:
    "other_namespace.collection1": ">=1.0.0"
    "other_namespace.collection2": ">=2.0.0,<3.0.0"
    "anderson55.my_collection": "*"    # note: "*" selects the highest version available
license:
    - "MIT"
tags:
    - demo
    - collection
repository: "https://www.github.com/my_org/my_collection"

Required Fields:

• namespace: the namespace that the collection lives under. It must be a valid Python identifier,

  may only contain alphanumeric characters and underscores. Additionally they cannot start with underscores or numbers and cannot contain consecutive underscores.

• name: the collection's name. Has the same character restrictions as namespace.
• version: the collection's version. To upload to Galaxy, it must be compatible with semantic versioning.

Optional Fields:

• dependencies: A dictionary where keys are collections, and values are version range 'specifiers <https://python-semanticversion.readthedocs.io/en/latest/#requirement-specification>`_, it is good practice to depend on a version range to minimize conflicts, and pin to a major version to protect against breaking changes, ex: "user1.collection1": ">=1.2.2,<2.0.0" allow other collections as dependencies, not traditional roles.
• description: A short summary description of the collection.
• license: Either a single license or a list of licenses for content inside of a collection. Galaxy currently only accepts SPDX licenses.
• tags: a list of tags. These have the same character requirements as namespace and name.
• repository: URL of originating SCM repository.

Docs

TBD. Intended to keep documentation for the collection here.

Plugins

Under here a collection can host a 'per plugin type' specific directory, including module_utils which is usable not only by modules

, but by any other plugin by using their 'fully qualified collection name' (FQCN for short). This is a way to distribute modules, lookup s, filters, etc without having to import a role in every play.

Roles

These are mostly the same as existing roles, but with a couple of limitations:

• Role names are now limited to contain only lowercase alphanumeric characters, plus _ and start with an alpha character.
• Roles cannot have their own plugins anymore, these must live in the collection and will be accessible to roles.

The directory name of the role is used as the role name, so therefore the directory name must comply with the above rules or not be usable.

Note

For roles imported into Galaxy directly from a GitHub repository, setting the role_name value in the role's metadata overrides the role name used by Galaxy. For collections, that value is ignored. When importing a collection, Galaxy uses the role directory as the name of the role and ignores the role_name metadata value.