Terminologie
Avant d’entrer dans le vif du sujet, quelques termes méritent d’être clarifiés :
- Ansible Collection — un ensemble d’automatisation pouvant contenir des rôles, des modules et des plugins. La plupart des modules sont écrits en Python (pour les serveurs Linux et les équipements réseau) ou en PowerShell (pour Windows).
- Ansible Role — un ensemble prédéfini de tâches, pouvant inclure des variables, des templates, des fichiers et des handlers. Un rôle peut être livré dans une collection ou exister de façon autonome.
- Config as Code (CaC) — la pratique consistant à définir et gérer la configuration par le code, ce qui permet l’automatisation, la réutilisation et le contrôle de version plutôt qu’une configuration manuelle.
Introduction
Je m’appelle Kristian et je suis l’auteur d’ebdruplab.semaphoreui, une Ansible Collection permettant de gérer votre installation de Semaphore UI par le code.
Comment tout a commencé
Le projet est né d’une envie d’approfondir ma maîtrise d’Ansible. Jusque-là, je consommais surtout des collections et des rôles écrits par d’autres, ou j’assemblais ansible.builtin.cmd, des registers et des templates Jinja2 pour arriver à mes fins.
Ma curiosité a d’abord été piquée par le besoin d’automatiser des équipements réseau assez obscurs — plus précisément, vérifier que les numéros de série en base de données étaient correctement renseignés. Après ce projet, je suis revenu à mon travail habituel en PowerShell, jusqu’à ce qu’une nouvelle mission de conseil me ramène vers Ansible. Cette mission couvrait tout : gestion des correctifs, aide à la mise en place de nœuds Ansible, conseil sur les bonnes pratiques et création de contenu pour installer Red Hat Single Sign-On.
Je travaille avec Ansible depuis sept ans — d’abord en CLI, puis avec Ansible Automation Platform (AAP) v2, avant de m’en éloigner. Pourquoi ? AAP est un produit puissant mais lourd, conçu pour les grandes entreprises. Il est pénible à installer en dehors d’OpenShift, et le coût des licences s’en ressent.
Pourquoi Semaphore UI
Semaphore UI m’a convaincu par sa simplicité. Un paquet, un serveur (sauf si vous avez besoin d’une échelle entreprise) — et non six machines virtuelles qui communiquent sur dix ports de dix manières différentes.
Oui, les execution environments d’AAP sont élégants. Mais les maintenir est une autre histoire. Semaphore UI est facile à mettre à jour, facile à exécuter, et propose une interface réactive et intuitive. Il lui manque certes quelques fonctions avancées, mais pour mes usages il offre le bon équilibre entre capacités et coût.
J’ai entendu parler de Semaphore pour la première fois dans la communauté homelab et je n’y ai pas prêté attention — jusqu’à ce que je l’essaie vraiment. Une fois sur Ansible Galaxy, constatant qu’aucune collection n’existait pour lui, la décision a été facile : ce serait mon projet d’apprentissage. Ai-je écrit tout le code moi-même ? Non — je me suis appuyé sur l’IA tout du long. Mais le projet a pris forme progressivement : trente minutes ici, une heure là. Rapidement, j’avais traduit toute l’API de Semaphore en modules Python.
Qu’est-ce que l’on peut en faire ?
Ansible Galaxy propose des exemples de ce que l’on peut faire avec ebdruplab.semaphoreui. Mais en voici quelques-uns :
Créer et gérer des projets — définissez vos projets Semaphore sous forme de code et déployez-les de façon reproductible
- name: Create project with token and custom settings
ebdruplab.semaphoreui.project_create:
host: http://localhost
port: 3000
api_token: "{{ semaphore_token }}"
name: "My Project"
alert: true
alert_chat: "#alerts"
max_parallel_tasks: 5
demo: false
Configurer des inventaires — gérez des inventaires statiques et dynamiques par programmation
- name: Create static inventory
ebdruplab.semaphoreui.project_inventory_create:
host: http://localhost
port: 3000
session_cookie: "{{ login_result.session_cookie }}"
project_id: 1
inventory:
name: "Local Static Inventory"
type: "static"
inventory: "localhost ansible_connection=local"
ssh_key_id: 42
become_key_id: 7
Mettre en place des templates de jobs — créez et mettez à jour des templates sans passer par l’interface
- name: Create template with UI-style override flags
ebdruplab.semaphoreui.project_template_create:
host: http://localhost
port: 3000
api_token: "{{ semaphore_token }}"
project_id: 1
template:
name: "ff"
playbook: "f"
repository_id: 1
inventory_id: 1
environment_id: 1
type: ""
arguments: "[]"
task_params:
allow_override_tags: true
allow_override_limit: true
tags: ["t"]
limit: ["t"]
Gérer les utilisateurs — automatisez la création des utilisateurs et leur affectation à un projet
- name: Create a new user
ebdruplab.semaphoreui.user_create:
host: http://localhost
port: 3000
session_cookie: "{{ login_result.session_cookie }}"
name: "Jane Smith"
username: "jsmith"
email: "[email protected]"
password: "supersecure123"
admin: true
alert: true
Sauvegarder des projets existants — exportez n’importe quel projet en production vers du YAML pour le versionner
- hosts: localhost
gather_facts: false
roles:
- role: ebdruplab.semaphoreui.project_backup
vars:
project_backup_semaphore_host: "https://semaphore.example.com"
project_backup_semaphore_api_token: "{{ lookup('env', 'SEMAPHORE_TOKEN') }}"
project_backup_project_name: "My Project"
Restaurer ou migrer — redéployez la configuration complète d’un projet à partir d’une définition YAML en quelques secondes.
- hosts: localhost
gather_facts: false
vars_files:
- vars/project.yml
roles:
- role: ebdruplab.semaphoreui.project_deploy
Config as Code — ebdruplab.project_deploy
Un module en est devenu deux. Deux en sont devenus dix. Au final, la collection a atteint 92 modules, couvrant les projets, les templates, les inventaires et bien plus encore.
À un moment, un utilisateur a demandé un rôle capable de servir de ciment entre tous ces modules. Ce rôle — ebdruplab.project_deploy — permet de décrire exactement à quoi doit ressembler un projet Semaphore UI, puis de le créer de manière déclarative via Ansible.
Voici à quoi ressemble une définition de projet minimale :
project_deploy_config:
project:
name: "My Project"
alert: false
alert_chat: ""
max_parallel_tasks: 0
demo: false
users_access:
- username: "admin"
role: "Owner"
keys:
repo_login:
name: "Git Login"
type: login_password
login_password:
login: "git-user"
password: "{{ vault_git_password }}"
repositories:
- name: "Example Repo"
git_url: "https://github.com/example/repo.git"
git_branch: "main"
key_name: "Git Login"
views:
main:
title: "Main"
position: 0
inventories:
local_inventory:
name: "Local Inventory"
type: "static"
inventory: "localhost ansible_connection=local"
environments:
default_env:
name: "Default Environment"
env:
APP_ENV: "prod"
templates:
deploy_job:
name: "Deploy"
type: "job"
repository_name: "Example Repo"
inventory_name: "Local Inventory"
environment_name: "Default Environment"
view_title: "Main"
playbook: "playbooks/site.yml"
schedules: {}
integrations: {}
La documentation est disponible sur Ansible Galaxy, et le dépôt GitHub contient des dossiers examples/ et test/ à la fois dans project_deploy et dans project_backup pour vous aider à démarrer.
Convertisseur Config as Code — ebdruplab.project_backup
Après avoir construit project_deploy, une autre idée m’est venue : que faire des projets Semaphore existants qui n’ont pas été créés par le code ? J’ai développé ebdruplab.project_backup exactement pour cela — il prend un projet existant et l’exporte sous forme de fichier YAML de variables compatible avec project_deploy.
La boucle est bouclée : que vous partiez de zéro ou que vous migriez une installation existante, vous pouvez tout placer sous contrôle de version.
Pour commencer
Installez la collection en une seule commande :
ansible-galaxy collection install ebdruplab.semaphoreui
Consultez ensuite la documentation complète sur Ansible Galaxy ou explorez les exemples sur GitHub.
Si vous trouvez une erreur ou avez une idée, n’hésitez pas à ouvrir un issue/feature/question : https://github.com/Ebdruplab/ansible-collection_ebdruplab/issues ; sinon, je traîne généralement sur les serveurs Discord de Semaphore UI — TrimmerWolf7.
J’espère que cette collection vous sera utile.
