Terminologia
Antes de entrar no assunto, vale esclarecer alguns termos:
- Ansible Collection — um pacote de automação que pode incluir roles, módulos e plugins. A maioria dos módulos é escrita em Python (para servidores Linux e equipamentos de rede) ou em PowerShell (para Windows).
- Ansible Role — um conjunto predefinido de tarefas, que pode incluir variáveis, templates, arquivos e handlers. Uma role pode ser distribuída dentro de uma collection ou existir de forma independente.
- Config as Code (CaC) — a prática de definir e gerenciar configuração por meio de código, permitindo automação, reutilização e controle de versão em vez de configuração manual.
Introdução
Meu nome é Kristian e sou o autor de ebdruplab.semaphoreui — uma Ansible Collection para gerenciar sua instalação do Semaphore UI por código.
Como começou
O projeto nasceu como uma forma de aprofundar meu conhecimento de Ansible. Até então, eu basicamente consumia collections e roles feitas por outras pessoas, ou juntava ansible.builtin.cmd, registers e templates Jinja2 para resolver as coisas.
Minha curiosidade foi despertada pela necessidade de automatizar alguns equipamentos de rede bem obscuros — especificamente, validar se os números de série no banco de dados estavam corretos. Depois desse projeto, voltei ao meu trabalho habitual com PowerShell, até que uma nova função de consultoria me trouxe de volta ao Ansible. Essa função envolvia de tudo: desde gestão de patches até ajudar a configurar nós do Ansible, orientar sobre boas práticas e criar conteúdo para instalar o Red Hat Single Sign-On.
Trabalho com Ansible há sete anos — comecei pela CLI, passei para o Ansible Automation Platform (AAP) v2 e acabei me afastando dele. Por quê? O AAP é um produto poderoso, mas pesado, feito para grandes empresas. É doloroso de configurar fora do OpenShift, e o custo do licenciamento reflete isso.
Por que Semaphore UI
O Semaphore UI me conquistou pela simplicidade. Um pacote, um servidor (a menos que você precise de escala enterprise) — e não seis VMs conversando por dez portas de dez maneiras diferentes.
Sim, os execution environments do AAP são elegantes. Mas mantê-los é outra história. O Semaphore UI é fácil de atualizar, fácil de rodar e traz uma interface responsiva e intuitiva. É verdade que faltam alguns recursos avançados, mas para os meus casos de uso ele atinge o equilíbrio certo entre capacidade e custo.
Ouvi falar do Semaphore pela primeira vez na comunidade de homelab e não dei muita bola — até experimentar de verdade. Quando conferi o Ansible Galaxy e não encontrei nenhuma collection para ele, a decisão foi fácil: esse seria meu projeto de aprendizado. Escrevi todo o código sozinho? Não — contei com a ajuda de IA o tempo todo. Mas o projeto foi tomando forma aos poucos: meia hora aqui, uma hora ali. Em pouco tempo eu havia traduzido toda a API do Semaphore em módulos Python.
O que dá para fazer com isso?
No Ansible Galaxy há exemplos do que se pode fazer com ebdruplab.semaphoreui. Mas seguem alguns:
Criar e gerenciar projetos — defina seus projetos do Semaphore como código e implante-os de forma repetível
- 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 inventários — gerencie inventários estáticos e 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 templates de jobs — crie e atualize templates sem tocar na 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"]
Gerenciar usuários — automatize a criação de usuários e a atribuição deles a um projeto
- 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
Fazer backup de projetos existentes — exporte qualquer projeto ativo para YAML e coloque-o sob controle de versão
- 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 ou migrar — reimplante a configuração completa de um projeto a partir de uma definição YAML em segundos.
- hosts: localhost
gather_facts: false
vars_files:
- vars/project.yml
roles:
- role: ebdruplab.semaphoreui.project_deploy
Config as Code — ebdruplab.project_deploy
Um módulo virou dois. Dois viraram dez. No fim, a collection chegou a 92 módulos, cobrindo projetos, templates, inventários e muito mais.
Em certo momento, um usuário pediu uma role que servisse de cola entre todos esses módulos. Essa role — ebdruplab.project_deploy — permite definir exatamente como um projeto do Semaphore UI deve ser e, então, criá-lo de forma declarativa via Ansible.
Veja como fica uma definição mínima de projeto:
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: {}
A documentação está disponível no Ansible Galaxy, e o repositório no GitHub inclui as pastas examples/ e test/ tanto em project_deploy quanto em project_backup para ajudar você a começar.
Conversor de Config as Code — ebdruplab.project_backup
Depois de construir o project_deploy, tive outra ideia: e os projetos do Semaphore que já existem e não foram criados por código? Criei o ebdruplab.project_backup exatamente para isso — ele pega um projeto existente e o exporta como um arquivo YAML de variáveis compatível com o project_deploy.
Isso fecha o ciclo: seja começando do zero ou migrando uma instalação existente, você consegue colocar tudo sob controle de versão.
Como começar
Instale a collection com um único comando:
ansible-galaxy collection install ebdruplab.semaphoreui
Depois, veja a documentação completa no Ansible Galaxy ou explore os exemplos no GitHub.
Se encontrar algum erro ou tiver uma ideia, não hesite em abrir um issue/feature/question: https://github.com/Ebdruplab/ansible-collection_ebdruplab/issues; caso contrário, costumo estar por perto nos servidores do Discord do Semaphore UI — TrimmerWolf7.
Espero que a collection seja útil para você.
