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 README.md 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.
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.
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