Terminología
Antes de entrar en materia, conviene aclarar algunos términos:
- Ansible Collection — un paquete de automatización que puede incluir roles, módulos y plugins. La mayoría de los módulos están escritos en Python (para servidores Linux y equipos de red) o en PowerShell (para Windows).
- Ansible Role — un conjunto predefinido de tareas, que puede incluir variables, plantillas, archivos y handlers. Un rol puede empaquetarse dentro de una colección o existir de forma independiente.
- Config as Code (CaC) — la práctica de definir y gestionar la configuración mediante código, lo que permite automatización, reutilización y control de versiones en lugar de configuración manual.
Introducción
Me llamo Kristian y soy el autor de ebdruplab.semaphoreui, una Ansible Collection para gestionar tu instalación de Semaphore UI mediante código.
Cómo empezó
El proyecto nació como una forma de profundizar en Ansible. Hasta entonces, sobre todo consumía colecciones y roles creados por otros, o iba encadenando ansible.builtin.cmd, registers y plantillas Jinja2 para sacar el trabajo adelante.
Mi curiosidad se despertó por la necesidad de automatizar unos equipos de red bastante peculiares; en concreto, validar que los números de serie de la base de datos estuvieran correctamente configurados. Después de ese proyecto volví a mi trabajo habitual con PowerShell, hasta que un nuevo puesto de consultoría me devolvió a Ansible. Aquel puesto incluía de todo: desde la gestión de parches hasta ayudar a montar nodos de Ansible, asesorar sobre buenas prácticas y crear contenido para instalar Red Hat Single Sign-On.
Llevo siete años trabajando con Ansible: empecé con la CLI, pasé a Ansible Automation Platform (AAP) v2 y finalmente me alejé de ella. ¿Por qué? AAP es un producto potente pero pesado, pensado para grandes empresas. Es doloroso de configurar fuera de OpenShift, y el coste de las licencias lo refleja.
Por qué Semaphore UI
Semaphore UI me conquistó por su simplicidad. Un paquete, un servidor (salvo que necesites escala empresarial), y no seis máquinas virtuales comunicándose por diez puertos de diez maneras distintas.
Sí, los execution environments de AAP son elegantes. Pero mantenerlos es otra historia. Semaphore UI es fácil de parchear, fácil de ejecutar y viene con una interfaz ágil e intuitiva. Es cierto que le faltan algunas funciones avanzadas, pero para mis casos de uso ofrece el equilibrio justo entre capacidades y coste.
Oí hablar de Semaphore por primera vez en la comunidad de homelab y no le di importancia, hasta que lo probé de verdad. Cuando revisé Ansible Galaxy y no encontré ninguna colección para él, la decisión fue fácil: este sería mi proyecto de aprendizaje. ¿Escribí todo el código yo mismo? No: me apoyé en la ayuda de la IA durante todo el proceso. Pero el proyecto fue tomando forma poco a poco: media hora aquí, una hora allá. En poco tiempo había traducido toda la API de Semaphore a módulos de Python.
¿Qué puedes hacer con ello?
En Ansible Galaxy hay ejemplos de lo que puedes hacer con ebdruplab.semaphoreui. Pero aquí van algunos:
Crear y gestionar proyectos — define tus proyectos de Semaphore como código y despliégalos de forma repetible
- 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
Configurar inventarios — gestiona inventarios estáticos y dinámicos de forma programática
- 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
Configurar plantillas de trabajos — crea y actualiza plantillas sin tocar la interfaz
- 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"]
Gestionar usuarios — automatiza la creación de usuarios y su asignación a un proyecto
- 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
Hacer copias de seguridad de proyectos existentes — exporta cualquier proyecto en producción a YAML para llevarlo al control de versiones
- 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"
Restaurar o migrar — vuelve a desplegar la configuración completa de un proyecto desde una definición YAML en segundos.
- hosts: localhost
gather_facts: false
vars_files:
- vars/project.yml
roles:
- role: ebdruplab.semaphoreui.project_deploy
Config as Code — ebdruplab.project_deploy
Un módulo se convirtió en dos. Dos se convirtieron en diez. Al final, la colección llegó a 92 módulos, que cubren proyectos, plantillas, inventarios y mucho más.
En cierto momento, un usuario pidió un rol que sirviera de pegamento entre todos esos módulos. Ese rol, ebdruplab.project_deploy, te permite definir exactamente cómo debe ser un proyecto de Semaphore UI y luego crearlo de forma declarativa con Ansible.
Así es como se ve una definición mínima de proyecto:
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 documentación está disponible en Ansible Galaxy, y el repositorio de GitHub incluye las carpetas examples/ y test/ dentro tanto de project_deploy como de project_backup para ayudarte a empezar.
Conversor de Config as Code — ebdruplab.project_backup
Después de crear project_deploy se me ocurrió otra idea: ¿qué pasa con los proyectos de Semaphore existentes que no se crearon con código? Construí ebdruplab.project_backup justo para eso: toma un proyecto existente y lo exporta como un archivo YAML de variables compatible con project_deploy.
Esto cierra el círculo: tanto si empiezas desde cero como si migras una instalación ya existente, puedes llevarlo todo al control de versiones.
Empezar
Instala la colección con un solo comando:
ansible-galaxy collection install ebdruplab.semaphoreui
Después consulta la documentación completa en Ansible Galaxy o explora los ejemplos en GitHub.
Si encuentras algún error o tienes una idea, no dudes en abrir un issue/feature/question: https://github.com/Ebdruplab/ansible-collection_ebdruplab/issues; si no, suelo andar por los servidores de Discord de Semaphore UI como TrimmerWolf7.
Espero que la colección te resulte útil.
