Creating and publishing Ansible Content Collections

Intro: Content collections are a distributable format for packaging and sharing your Ansible content. This lesson covers how to create and publish a collection to Ansible Galaxy.

In this lesson, you will:

• Learn how to create collections using the ansible-galaxy CLI.
• Learn how to configure your environment to publish collections to Ansible Galaxy.
• Learn how to publish Content Collections in Ansible Galaxy.

 Prerequisites: For this lesson, you will need an Ansible Galaxy account. Ansible Galaxy uses GitHub for authentication. If you still need to set up an account, please follow the instructions on the Ansible Galaxy homepage.

 Collection namespaces in Ansible Galaxy 

A collection namespace typically relates to the organization or group maintaining the collection. Your Ansible Galaxy username is usually also your Ansible Galaxy namespace name.

Initializing a new collection 

You can create new collections using the ansible-galaxy collection init command. By default, this command creates a new collection skeleton in the current directory.

Let’s use an example to illustrate initializing collections. We’ll create a new collection called webserver. 

1. Open your command prompt.

2. Type the following command:

   ansible-galaxy collection install <your_namespace>.webserver

3. Replace <your_namespace> with the name of your Ansible Galaxy namespace. 

For example, if we run the ansible-galaxy collection install aap_rocks.webserver command, we will get a new folder structure similar to the output below.

aap_rocks/
└── webserver/
    ├── docs/
    ├── galaxy.yml
    ├── plugins/
    ├── README.md
    ├── roles/
    ├── meta/
        └── runtime.yml

Example aap_rocks.webserver Collection structure.

Preparing your collection for publishing

Once you have created the content you want to include in the webserver collection, we must prepare it for publishing.

Collection metadata in the galaxy.yml file

The galaxy.yml file contains metadata about the collection and instructions for building the artifact and must be updated before publishing a collection. 

Below is a simple example of a galaxy.yml file:

namespace: aap_rocks                    # Collection namespace
name: webserver                         # Collection name
version: 1.0.0                          # Collection semantic version
authors:                                # List of authors
  - AAP Rocks <aap-rocks@example.com>   
description: Automates web server tasks # Collection description
license:
  - MIT                                 # Collection license
tags:                                   # Tags to help find collection.
  - networking                
  - web                       
readme: README.md                       # Path to the main README file
dependencies:                           # List of dependencies
  "aap_rocks.infra_collection": ">=1.0.0"
repository: https://github.com/aap_rocks/webserver-collection 

Example galaxy.yml file.

• namespace: - (required) The collection namespace. In our example, it’s aap_rocks. 
• name: - (required) The name of the collection. In this example, the name is webserver. 
• version: - (required) The semantic version of the collection. 1.0.0 in our example 
• authors: - (required) The collection authors. Our author is AAP Rocks . <aap-rocks@example.com>.
• repository: - (required) This repository hosts the collection. In our example, it’s the https://github.com/aap_rocks/webserver-collection repository. 
• description: - This description is visible in repositories and helps users understand the purpose of the collection. 
• license: - Specifies under what license your collection is distributed. MIT in our example. 
• tags: - Keywords that describe our collection and make it searchable.
• readme: - The main Markdown README that acts as the entry point for documentation about the collection. 
• dependencies: - Collections that our collection depends on to work. In our example, the webserver collection depends on version >=1.0.0 of the aap_rocks.infra_collection.

Please read the Ansible documentation for a complete list of configuration options.

Collection metadata in the  meta/runtime.yml file

We will also need to update the meta/runtime.yml file and configure the compatible Ansible Core versions for the collection:

---
requires_ansible: '>=2.15.0'

Example meta/runtime.yml file.

• requires_ansible - Specifies which versions of Ansible Core are compatible with the Collection. For example, >=2.15.0.

Your turn!

Let’s update the galaxy.yml file in our webserver collection:

1. Copy the content below into your galaxy.yml file in the root of the webserver Collection.

   namespace: <your_namespace>
   name: webserver
   version: 1.0.0
   authors:
     - <Your Name and email address>  
   description: Automates web server tasks
   license:
     - <Collection license>
   tags:
     - networking
     - web
   readme: README.md

   Practical galaxy.yml file example.

2. Update the following fields to the appropriate values:

• namespace: - Update this to your Ansible Galaxy namespace name. 
• authors: - Add your details using your name and email address. 
• license: - Select an appropriate license to distribute the Collection.

Next, we’ll update the meta/runtime.yml file:

1. Copy the content below into your meta/runtime.yml relative to the root of the webserver Collection:

---
requires_ansible: '>=2.13.10, <2.16.0'

Example meta/runtime.yml file.

Building a content collection 

The ansible-galaxy collection build command builds the collection artifact as a .tar.gz archive. This command should be run from within the collection's root directory.

1. Open your terminal.
2. Navigate to the collection root directory—for example, aap_rocks/webserver.
3. Run the following command. 

ansible-galaxy collection build

If the command completes successfully, you should see a similar output to:

Created collection for aap_rocks.webserver at /home/my_user/my_project/webserver/aap_rocks-webserver-1.0.0.tar.gz

Publishing a content collection to a repository 

Once we’ve successfully built a collection, we can publish it to a central repository for distribution. We’ll use the ansible-galaxy collection publish command and authenticate using an Ansible Galaxy API token to do this.

Create an Ansible Galaxy API token

We must create an Ansible Galaxy API token to publish collections in the repository. Follow the steps below to accomplish this:

1. Log into Ansible Galaxy by clicking on the Login button. 
2. Click Collections on the left-hand side navigation pane and select API token.
3. Click on Load token (Figure 1).

 Let’s publish our webserver collection to Ansible Galaxy. You will need the Ansible Galaxy API token we created earlier.

1. Open your terminal.
2. Run the following command:

ansible-galaxy collection publish <your_local_path>/webserver/aap_rocks-webserver-1.0.0.tar.gz --api-key <your_api_key>

• <your_local_path> - Replace this with the path of your webserver collection folder. 
• <your_api_key> - Replace with the Ansible Galaxy token we created earlier.

If the command completes successfully, you should see a similar output to:

Publishing collection artifact '/<local_path>/webserver/aap_rocks-webserver-1.0.0.tar.gz' to default https://galaxy.ansible.com/api/
Collection has been published to the Galaxy server default https://galaxy.ansible.com/api/
…

Well done!

Congratulations on completing the “Getting started with Ansible Content Collections” learning path. Want to learn more? You can find more learning paths in our Ansible learning hub.

Below you will find links to additional resources.

Happy automating!

Additional resources

• Start a free trial to Ansible Automation Platform
• Documentation: Developing Ansible Collections

Have feedback on this learning path? Share it with us.