Terminologia
Prima di entrare nel merito, vale la pena chiarire alcuni termini:
- Ansible Collection — un pacchetto di automazione che può includere ruoli, moduli e plugin. La maggior parte dei moduli è scritta in Python (per server Linux e apparati di rete) o in PowerShell (per Windows).
- Ansible Role — un insieme predefinito di task, che può includere variabili, template, file e handler. Un ruolo può essere incluso in una collection oppure esistere in modo autonomo.
- Config as Code (CaC) — la pratica di definire e gestire la configurazione tramite codice, abilitando automazione, riuso e controllo di versione al posto della configurazione manuale.
Introduzione
Mi chiamo Kristian e sono l’autore di ebdruplab.semaphoreui, una Ansible Collection per gestire la tua installazione di Semaphore UI tramite codice.
Come è cominciata
Il progetto è nato come modo per approfondire Ansible. Fino a quel momento avevo per lo più usato collection e ruoli scritti da altri, oppure messo insieme ansible.builtin.cmd, register e template Jinja2 per arrivare al risultato.
La mia curiosità è nata dalla necessità di automatizzare alcuni apparati di rete piuttosto insoliti: in particolare, verificare che i numeri di serie nel database fossero impostati correttamente. Dopo quel progetto sono tornato al mio lavoro abituale in PowerShell, finché un nuovo incarico di consulenza mi ha riportato ad Ansible. Quell’incarico comprendeva di tutto: dalla gestione delle patch all’aiuto nella configurazione dei nodi Ansible, dalla consulenza sulle best practice alla creazione di contenuti per installare Red Hat Single Sign-On.
Lavoro con Ansible da sette anni: ho iniziato dalla CLI, sono passato ad Ansible Automation Platform (AAP) v2 e alla fine me ne sono allontanato. Perché? AAP è un prodotto potente ma pesante, pensato per le grandi aziende. È faticoso da installare fuori da OpenShift, e il costo delle licenze lo riflette.
Perché Semaphore UI
Semaphore UI mi ha conquistato con la sua semplicità. Un pacchetto, un server (a meno che non serva una scala enterprise), non sei VM che comunicano su dieci porte in dieci modi diversi.
Sì, gli execution environment di AAP sono eleganti. Ma mantenerli è un’altra storia. Semaphore UI è facile da aggiornare, facile da eseguire e offre un’interfaccia reattiva e intuitiva. Qualche funzione avanzata manca, ma per i miei casi d’uso trova il giusto equilibrio tra funzionalità e costo.
Ho sentito parlare di Semaphore per la prima volta nella comunità homelab e non ci ho dato peso, finché non l’ho provato davvero. Quando poi ho controllato Ansible Galaxy e non ho trovato nessuna collection dedicata, la decisione è stata facile: sarebbe stato il mio progetto di apprendimento. Ho scritto tutto il codice da solo? No: mi sono appoggiato all’AI lungo tutto il percorso. Ma il progetto ha preso forma poco a poco: mezz’ora qui, un’ora là. In poco tempo avevo tradotto l’intera API di Semaphore in moduli Python.
Che cosa ci puoi fare?
Su Ansible Galaxy ci sono esempi di ciò che si può fare con ebdruplab.semaphoreui. Ma eccone alcuni:
Creare e gestire progetti — definisci i tuoi progetti Semaphore come codice e distribuiscili in modo ripetibile
- 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
Configurare gli inventory — gestisci inventory statici e dinamici in modo programmatico
- 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
Impostare i template dei job — crea e aggiorna i template senza toccare l’interfaccia
- 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"]
Gestire gli utenti — automatizza la creazione degli utenti e la loro assegnazione a un progetto
- 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
Fare il backup di progetti esistenti — esporta qualsiasi progetto attivo in YAML per metterlo sotto controllo di versione
- 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"
Ripristinare o migrare — ridistribuisci in pochi secondi l’intera configurazione di un progetto a partire da una definizione YAML.
- hosts: localhost
gather_facts: false
vars_files:
- vars/project.yml
roles:
- role: ebdruplab.semaphoreui.project_deploy
Config as Code — ebdruplab.project_deploy
Un modulo è diventato due. Due sono diventati dieci. Alla fine la collection è arrivata a 92 moduli, che coprono progetti, template, inventory e molto altro.
A un certo punto un utente ha chiesto un ruolo che facesse da collante tra tutti questi moduli. Quel ruolo — ebdruplab.project_deploy — ti permette di definire esattamente come dovrebbe essere un progetto Semaphore UI e poi di crearlo in modo dichiarativo tramite Ansible.
Ecco come si presenta una definizione minima di progetto:
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 documentazione è disponibile su Ansible Galaxy e il repository GitHub include le cartelle examples/ e test/ sia in project_deploy sia in project_backup per aiutarti a iniziare.
Convertitore Config as Code — ebdruplab.project_backup
Dopo aver costruito project_deploy mi è venuta un’altra idea: e i progetti Semaphore già esistenti, quelli non creati tramite codice? Ho realizzato ebdruplab.project_backup proprio per questo: prende un progetto esistente e lo esporta come file YAML di variabili compatibile con project_deploy.
Così il cerchio si chiude: che tu parta da zero o stia migrando una configurazione esistente, puoi portare tutto sotto controllo di versione.
Come iniziare
Installa la collection con un solo comando:
ansible-galaxy collection install ebdruplab.semaphoreui
Poi vai alla documentazione completa su Ansible Galaxy oppure esplora gli esempi su GitHub.
Se trovi errori o hai un’idea, non esitare ad aprire un issue/feature/question: https://github.com/Ebdruplab/ansible-collection_ebdruplab/issues, altrimenti di solito bazzico i server Discord di Semaphore UI come TrimmerWolf7.
Spero che la collection ti sia utile.
