Publish multiple roles using Ansible-Galaxy Collections

When we want to publish multiple ansible roles as a package then we have to create an ansible-galaxy collection. The collection will allow us to upload multiple roles together. At the same time, it will allow versioning.

I’m assuming you have already created ansible roles.

So, for creating an ansible-collection follow the following steps.

Step 1: Create your ansible-galaxy account

You will have a default namespace as that of your username. In my case it’s cankush625.

Step 2: Starting a new collection

To start a new collection, run the following command

$ ansible-galaxy collection init my_namespace.my_collection

Here, my_namespace is the name of your ansible-galaxy namespace as discussed in step 1. And my_collection is the name you want to give to your collection.

This command will create a skeleton (file structure) of the ansible-galaxy collection.

Step 3: Understanding the collection file structure

For now, we have one directory of use that is the roles/

Inside the roles/ directory, we will copy all of the roles that we want to upload in the current collection.


The most important file for us is the galaxy.yml file. This is the file in which we will write all of the details about the collection.

  • At the very beginning, we will write the namespace name using the namespace keyword.
  • Write the name of the collection using the name keyword.
  • A version of the collection using the version keyword.
  • Write the authors of the collection using the authors keyword. The authors of the collection can be in the format Author name <Email>. You can write a list of authors.
  • Description of the collection using the description keyword.
  • Specify the license file using the license_file keyword. It will only detect the license if the license is present at the root directory of the collection.
  • Specify the relevant tags using the tags keyword. You can find the available tags on the ansible-galaxy website.
  • Lastly, you can specify the GitHub repository, documentation URL, homepage URL, issue tracker URL, etc.

Create documentation for your collection using the file.

Step 4: Build the collection

Run the following command for building the collection:

$ ansible-galaxy collection build cankush625/kubernetescluster/

In the above command, cankush625/kubernetescluster/ is the location where the galaxy.yml file and roles/ directory is present.

This command will create a tarball package that contains the packaged collection. Now, this collection is ready to publish to the ansible-galaxy.

Step 5: Publish the collection

The ansible collection can be published using the tarball file we had created in step 4.

There are two methods for publishing the collection.

Method 1:

Go to the ansible-galaxy web console, click on the my-content button from the options at left. After that, click on Add content button. This will open up a dialogue that will ask to upload the collection. Click on upload new collection and select the tarball package that we had created in step 4 and upload it. That’s it! You had published your ansible-galaxy collection.

Method 2:

Go to the command line and run the following command

$ ansible-galaxy collection publish YOUR_COLLECTION.tar.gz --api-key=YOUR_API_KEY

Here, you need an API key for publishing the package from the command line.

Steps to get the API Key:

Go to the preferences by clicking on your ansible-galaxy username and click on preferences.

Click on the show API key.

This will show you the API key. Copy this API key and use it in the above command for publishing the ansible-galaxy collection.

Step 6: Using the collection

Run the following command to install the collection:

$ ansible-galaxy collection install YOUR_NAMESPACE.COLLECTION_NAME

Ansible-Galaxy collection source code for your reference:

My Ansible-Galaxy collection:

For any help or suggestions connect with me on Twitter at @TheNameIsAnkush or find me on LinkedIn.

Thank you!



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Ankush Chavan

Ankush Chavan

Tech blogger, researcher and integrator