Ansible Galaxy

---

Chapter objectives

• Discover Ansible Galaxy
• Install roles and collections
• Manage dependencies
• Publish your own roles

---

1 - What is Ansible Galaxy?

Overview

Ansible Galaxy is:

• A community hub of roles and collections
• A CLI tool to manage content
• A way to share your work

Roles vs Collections

Roles	Collections
Tasks + handlers + vars	Roles + modules + plugins
Simple format	Full format
Single purpose	Suite of related tools
namespace.role	namespace.collection

---

2 - Search for content

Via the website

👉 https://galaxy.ansible.com

Via the CLI

# Rechercher des rôles
ansible-galaxy search nginx
ansible-galaxy search postgresql --author geerlingguy

# Informations sur un rôle
ansible-galaxy info geerlingguy.nginx

# Lister les rôles installés
ansible-galaxy list

Popular collections

Collection	Description
community.general	General modules
community.docker	Docker management
amazon.aws	AWS resources
azure.azcollection	Azure resources
kubernetes.core	Kubernetes

---

3 - Install roles

Simple installation

# Installer un rôle
ansible-galaxy install geerlingguy.nginx

# Avec version spécifique
ansible-galaxy install geerlingguy.nginx,3.1.0

# Dans un dossier personnalisé
ansible-galaxy install geerlingguy.nginx -p roles/

The requirements.yml file

# requirements.yml
---
roles:
  # Depuis Galaxy
  - name: geerlingguy.nginx
    version: "3.1.0"
  
  - name: geerlingguy.postgresql
    version: "3.4.0"
  
  # Depuis Git
  - name: my-nginx
    src: https://github.com/myorg/ansible-nginx.git
    scm: git
    version: master
  
  # Depuis une archive
  - name: custom-role
    src: https://example.com/roles/custom.tar.gz

collections:
  # Collections
  - name: community.docker
    version: "3.4.0"
  
  - name: amazon.aws
    version: ">=5.0.0"

Install from requirements

# Installer tous les rôles et collections
ansible-galaxy install -r requirements.yml

# Forcer la réinstallation
ansible-galaxy install -r requirements.yml --force

# Installer seulement les rôles
ansible-galaxy role install -r requirements.yml

# Installer seulement les collections
ansible-galaxy collection install -r requirements.yml

---

4 - Install collections

CLI

# Installer une collection
ansible-galaxy collection install community.docker

# Version spécifique
ansible-galaxy collection install community.docker:3.4.0

# Depuis un fichier tar.gz
ansible-galaxy collection install ./my_collection-1.0.0.tar.gz

# Lister les collections installées
ansible-galaxy collection list

Installation paths

# Installer dans le projet
ansible-galaxy collection install community.docker -p ./collections/

# Configuration dans ansible.cfg
[defaults]
collections_paths = ./collections:~/.ansible/collections

---

5 - Use the installed content

Use a Galaxy role

# playbook.yml
---
- name: Configure web servers
  hosts: webservers
  become: yes
  
  roles:
    - geerlingguy.nginx
    - geerlingguy.php

Use a collection

---
- name: Gérer Docker
  hosts: all
  become: yes
  
  collections:
    - community.docker
  
  tasks:
    - name: Créer un réseau Docker
      docker_network:
        name: mynetwork
    
    - name: Lancer un conteneur
      docker_container:
        name: nginx
        image: nginx:alpine
        ports:
          - "80:80"

FQCN (Fully Qualified Collection Name)

tasks:
  # Sans FQCN (si collection déclarée)
  - name: Docker container
    docker_container:
      name: app
      image: myapp
  
  # Avec FQCN (recommandé)
  - name: Docker container
    community.docker.docker_container:
      name: app
      image: myapp

---

6 - Manage dependencies

Project structure

my-project/
├── ansible.cfg
├── requirements.yml        # Dépendances
├── collections/            # Collections installées
├── roles/                  # Rôles installés
├── inventory/
└── playbooks/

ansible.cfg

[defaults]
roles_path = ./roles:~/.ansible/roles
collections_paths = ./collections:~/.ansible/collections

[galaxy]
server_list = release_galaxy
ignore_certs = false

[galaxy_server.release_galaxy]
url = https://galaxy.ansible.com/

Installation script

#!/bin/bash
# setup.sh

echo "Installation des dépendances Ansible..."

# Installer les collections et rôles
ansible-galaxy install -r requirements.yml

# Vérifier l'installation
echo "Rôles installés:"
ansible-galaxy list

echo "Collections installées:"
ansible-galaxy collection list

echo "Setup terminé!"

---

7 - Create and publish a role

Create the skeleton

ansible-galaxy init --init-path roles/ my_role

# Structure créée
roles/my_role/
├── README.md
├── defaults/main.yml
├── handlers/main.yml
├── meta/main.yml
├── tasks/main.yml
├── templates/
├── tests/
│   ├── inventory
│   └── test.yml
└── vars/main.yml

Configure meta/main.yml

# meta/main.yml
---
galaxy_info:
  author: votre_nom
  description: Description du rôle
  company: Ma Société
  license: MIT
  min_ansible_version: "2.10"
  
  platforms:
    - name: Ubuntu
      versions:
        - focal
        - jammy
    - name: Debian
      versions:
        - bullseye
        - bookworm
  
  galaxy_tags:
    - nginx
    - webserver
    - web

dependencies: []

Publish to Galaxy

# 1. Créer un compte sur galaxy.ansible.com

# 2. Connecter GitHub à Galaxy

# 3. Importer le rôle
# Via l'interface web Galaxy

# Ou via CLI (avec token)
ansible-galaxy login
ansible-galaxy import username repository_name

---

8 - Create a collection

Initialize

ansible-galaxy collection init mycompany.mycollection

# Structure
mycompany/mycollection/
├── docs/
├── galaxy.yml
├── plugins/
│   ├── modules/
│   ├── inventory/
│   └── filter/
├── README.md
└── roles/

galaxy.yml

# galaxy.yml
namespace: mycompany
name: mycollection
version: 1.0.0
readme: README.md
authors:
  - Your Name <[email protected]>
description: Ma collection personnalisée
license:
  - MIT
license_file: LICENSE
tags:
  - devops
  - infrastructure
repository: https://github.com/mycompany/mycollection
documentation: https://docs.example.com
homepage: https://example.com
issues: https://github.com/mycompany/mycollection/issues

dependencies:
  community.general: ">=5.0.0"

Build and publish

# Construire
ansible-galaxy collection build

# Publier
ansible-galaxy collection publish mycompany-mycollection-1.0.0.tar.gz --api-key=YOUR_KEY

---

9 - Private Galaxy / Automation Hub

Architecture

AWX / Automation Hub

For enterprises:

• AWX: Open-source version of Automation Controller
• Automation Hub: Private Galaxy (Red Hat)

Multi-server configuration

# ansible.cfg
[galaxy]
server_list = automation_hub, release_galaxy

[galaxy_server.automation_hub]
url = https://hub.mycompany.com/api/galaxy/
token = my_token

[galaxy_server.release_galaxy]
url = https://galaxy.ansible.com/

---

10 - Best practices

Versioning

# requirements.yml - Toujours spécifier les versions
roles:
  - name: geerlingguy.nginx
    version: "3.1.0"  # ✅ Version fixe

collections:
  - name: community.docker
    version: ">=3.0.0,<4.0.0"  # ✅ Range de versions

Updating

# Vérifier les mises à jour
ansible-galaxy role list
ansible-galaxy collection list

# Mettre à jour
ansible-galaxy install -r requirements.yml --force

CI/CD

# .github/workflows/ansible.yml
name: Ansible CI

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install Ansible
        run: pip install ansible ansible-lint
      
      - name: Install dependencies
        run: ansible-galaxy install -r requirements.yml
      
      - name: Lint playbooks
        run: ansible-lint playbooks/

---

Summary

Key points

• Use requirements.yml to manage dependencies
• Prefer FQCN for collection modules
• Always version your dependencies
• Explore geerlingguy's roles (quality)

---

Practical exercises

1. Install the geerlingguy.docker role via Galaxy
2. Create a requirements.yml with several dependencies
3. Use a collection in a playbook
4. Create a role skeleton with ansible-galaxy init

---

← Templates | Exercises and projects →