In this tutorial, we'll discuss Ansible Galaxy how to use and contribute roles.
Ansible Galaxy is a community hub for finding, sharing, and downloading Ansible roles and collections. Roles provide pre-packaged automation scripts that help simplify complex tasks, while collections contain roles, plugins, and modules. This guide will cover how to use roles from Ansible Galaxy, create your own roles, and customize them to fit your needs. By the end, you’ll know how to contribute roles to the community.
What is Ansible Galaxy?
Ansible Galaxy is both a website and a command-line tool. The website serves as a central repository where users can find and download ready-to-use Ansible roles. The command-line tool, ansible-galaxy, is used to interact with the Galaxy repository, allowing you to install, search, and manage roles.
Key Concepts:
- Role: A way to package and distribute Ansible automation code. It includes tasks, variables, files, templates, and handlers.
- Collection: A distribution format that includes roles, modules, and plugins in one package.
- Galaxy: A public repository for sharing and discovering roles and collections.
- How to Use Ansible Galaxy to Find and Use Roles
Step 1: Search for Roles
Before using a role, you need to find it. You can search for roles directly from the Ansible Galaxy website or use the ansible-galaxy command-line tool.
Searching from the Command Line:
ansible-galaxy search <role_name>
For example:
ansible-galaxy search nginx
This command will show a list of roles related to "nginx" along with their ratings, downloads, and a short description.
Step 2: Install a Role
Once you've identified a role you want to use, install it using the ansible-galaxy install command.
Installing a Role:
ansible-galaxy install <author.role_name>
For example:
ansible-galaxy install geerlingguy.nginx
This will download the role and save it to the default roles path, usually ~/.ansible/roles.
Step 3: Use the Role in a Playbook
To use the downloaded role, reference it in your playbook:
Example Playbook (site.yml):
---
- hosts: webservers
become: yes
roles:
- geerlingguy.nginx
Run the playbook with the standard ansible-playbook command:
ansible-playbook site.yml
Step 4: Manage Installed Roles
To see a list of all installed roles, use:
ansible-galaxy list
To remove an installed role:
ansible-galaxy remove <author.role_name>
How to Create Your Own Ansible Role
Creating custom roles helps you automate tasks specific to your infrastructure. Follow these steps to create and publish your role.
Step 1: Create a Role Skeleton
Ansible provides a built-in command to generate the skeleton for a new role:
ansible-galaxy init <role_name>
For example:
ansible-galaxy init my_custom_role
This command creates the following directory structure:
my_custom_role/
├── README.md
├── defaults/
│ └── main.yml
├── files/
├── handlers/
│ └── main.yml
├── meta/
│ └── main.yml
├── tasks/
│ └── main.yml
├── templates/
├── tests/
│ └── inventory
│ └── test.yml
└── vars/
└── main.yml
Step 2: Add Tasks to Your Role
Edit the tasks/main.yml file to define the tasks your role will perform. Here’s an example of a simple task to install nginx:
tasks/main.yml:
---
# tasks file for my_custom_role
- name: Install Nginx
apt:
name: nginx
state: present
when: ansible_os_family == 'Debian'
Step 3: Test Your Role
You can test the role by creating a simple playbook:
Test Playbook (test.yml):
---
- hosts: localhost
become: yes
roles:
- my_custom_role
Run the playbook to ensure everything works:
ansible-playbook test.yml
Step 4: Add Metadata and Dependencies
Edit the meta/main.yml file to add metadata about your role. This is crucial if you want to share your role on Ansible Galaxy.
Example meta/main.yml:
---
galaxy_info:
author: your_username
description: A role to install and configure Nginx.
license: MIT
min_ansible_version: 2.9
platforms:
- name: Debian
versions:
- buster
- bullseye
dependencies: []
Step 5: Publish Your Role to Ansible Galaxy
To publish your role to Ansible Galaxy, follow these steps:
Log in to Ansible Galaxy and create an API token under your user profile.
Set up Ansible Galaxy with your token:
ansible-galaxy login
Publish the role:
ansible-galaxy role import <GitHub_username> <repository_name>
Ensure that your role is hosted on a public GitHub repository before importing it.
Customizing Downloaded Roles
Sometimes, a downloaded role might not fit your exact needs. Instead of modifying it directly, you can customize it in a way that retains the original role’s functionality.
Method 1: Override Variables
Most roles allow customization via variables. Check the role’s defaults/main.yml file to see what variables can be overridden.
Example (site.yml):
---
- hosts: webservers
become: yes
roles:
- role: geerlingguy.nginx
vars:
nginx_worker_processes: 4
nginx_http_port: 8080
Method 2: Use the Role as a Base and Extend It
If you need more complex changes, create a wrapper role. The wrapper role can call the original role and then add additional tasks or custom configurations.
Wrapper Role (tasks/main.yml):
---
# Include the base role
- include_role:
name: geerlingguy.nginx
# Add custom tasks
- name: Copy custom nginx config
template:
src: custom_nginx.conf.j2
dest: /etc/nginx/nginx.conf
Method 3: Fork the Role
If significant changes are required, fork the role’s GitHub repository, modify it to suit your needs, and host it in your own repository.
Steps to Fork a Role:
- Fork the original role’s repository on GitHub.
- Clone the forked repository to your local system.
- Make the necessary modifications.
- Use your forked version in your playbooks.
Using a Forked Role:
ansible-galaxy install git+https://github.com/yourusername/forked_role.git
Best Practices for Ansible Galaxy Roles
- Keep Roles Modular: Ensure roles focus on a single task or service.
- Use Tags: Tag tasks for easy control during playbook runs.
- Provide Defaults: Use defaults/main.yml for default values and let users override them.
- Add Tests: Include a tests directory with playbooks to validate the role.
- Version Your Roles: Use Git tags to mark stable releases.
Conclusion
Ansible Galaxy is a powerful tool for automating infrastructure management. You can save time by leveraging community roles, create your own for customized needs, and contribute back to the community. This guide covered everything from finding and using roles to creating and publishing your own. With a clear understanding of roles, you’ll be able to manage complex environments efficiently using Ansible.
Checkout our dedicated servers India, Instant KVM VPS, and Web Hosting India
