De playbooks soltos a templates governados no Semaphore

Um diretório cheio de playbooks Ansible pode representar anos de conhecimento operacional.

Também pode representar anos de exceções, nomes históricos, automações duplicadas e ações de riscos completamente diferentes misturadas na mesma pasta.

Quando comecei a organizar esse tipo de acervo para execução via Semaphore, a decisão mais importante não foi criar templates rapidamente.

Foi fazer o contrário:

não transformar tudo em botão antes de entender o que cada botão faria.

O problema de “subir tudo no Semaphore” #

Imagine playbooks com nomes como:

1
2
3
4
5
6
7

health_check.yml
restart_container.yml
deploy_api.yml
resize_cloud.yml
audit_redis.yml
migrate_domain.yml
collect_logs.yml

Todos são YAML.

Operacionalmente, não são equivalentes.

Um health check pode apenas coletar informação.

Um restart interrompe processo.

Um deploy troca código.

Um resize altera infraestrutura cloud.

Uma migração de domínio pode afetar tráfego real.

Se todos entram como templates com o mesmo nível de acesso, o orquestrador só tornou o blast radius mais fácil de alcançar.

Primeiro criar inventário, não templates #

Na plataforma que originou este artigo, a documentação começou com uma tabela de inventário.

Para cada playbook, os campos planejados incluíam:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

arquivo
projeto
ativo?
categoria
risco
inventory
variáveis
secrets
template sugerido
liberação para operadores
status

Mesmo quando várias colunas ainda estavam como “a mapear”, isso já era melhor do que presumir que o nome do arquivo explicava a operação.

O inventário cria uma fila explícita de trabalho.

Nome é pista, não prova #

Um arquivo chamado:

1

ajuste_redis.yml

pode fazer qualquer coisa entre:

1

ler configuração

e:

1

reiniciar Redis e alterar parâmetros

Por isso a classificação inicial pelo nome foi marcada como preliminar.

A classificação final depende da leitura do conteúdo.

Esse cuidado é especialmente importante em repositórios antigos, onde o nome permanece e o comportamento evolui.

O template precisa responder perguntas que o playbook sozinho não responde #

Antes de liberar um template para outra pessoa executar, eu quero saber:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Qual é a finalidade?
Qual inventory ele espera?
Que target pode receber?
Quais variáveis são obrigatórias?
Que secrets utiliza?
Pode alterar produção?
Tem dry-run/check mode útil?
Tem proteção contra alvo vazio/amplo?
Como validar o resultado?
Quem pode executá-lo?

Se essas respostas não existem, o template ainda é uma interface bonita para uma operação desconhecida.

Categorias ajudam a enxergar duplicidade #

O inventário real separou famílias como:

1
2
3
4
5
6
7
8
9

diagnóstico
Redis
PostgreSQL
Docker/API/deploy
OCI
observabilidade
Nginx/domínio
ativação
scanner/auditoria

Quando os arquivos são agrupados por finalidade, aparecem perguntas melhores:

1
2
3
4

Por que existem três deploys parecidos?
Qual health check é o atual?
Esse restart é usado por qual aplicação?
Dois playbooks de OCI se sobrepõem?

A duplicidade que não aparece numa lista alfabética costuma aparecer rapidamente numa visão por categoria.

Templates LOW são bons candidatos iniciais #

Uma regra da documentação era começar por ações de menor risco.

Por exemplo:

1
2
3
4
5
6

ping
facts
health check
listar eventos
ler logs
coletar inventário

Isso valida:

• repositório;
• chave SSH;
• inventory;
• Ansible config;
• permissões;
• variáveis;
• experiência do operador;
• logging do Semaphore.

Sem precisar começar com um deploy ou restart de produção.

Um template é um contrato operacional #

No Semaphore, um template agrega mais contexto do que o arquivo YAML.

Ele pode definir:

1
2
3
4
5
6
7

repositório
playbook
inventory
environment/variable group
survey
permissões
limite operacional

Então o template deve ser tratado como uma interface estável.

O playbook pode ter várias variáveis internas; o operador não precisa necessariamente ver todas.

O Survey deve expor apenas o que faz sentido decidir na execução.

Variável global não deve virar pergunta repetida #

Se um projeto sempre usa um profile cloud específico, perguntar em toda execução:

1

Qual AWS_PROFILE?

só cria oportunidade para selecionar o valor errado.

No modelo documentado, valores fixos do projeto ficam em Variable Group.

O Survey recebe apenas parâmetros da tarefa atual, como:

1
2
3
4
5

target
ambiente
motivo
ticket
dry_run

Isso reduz ruído e risco.

Separar execução de edição é uma decisão de segurança #

Outro ponto importante foi criar um papel de operador que pudesse rodar receitas prontas sem editar:

1
2
3
4
5

repository
inventory
variable group
key store
template

A ideia é simples:

delegar execução não precisa significar delegar autoria da automação.

Se a pessoa pode editar o playbook/template e executar imediatamente, parte do controle de mudança desaparece.

Não reorganizar fisicamente antes da análise #

A documentação do projeto diz explicitamente para não mover os playbooks antes de classificar.

Isso parece conservador, e é.

Mover arquivos enquanto ainda se tenta descobrir:

• qual é ativo;
• qual é legado;
• qual duplica outro;
• quem referencia aquele path;

cria uma segunda mudança no meio da primeira investigação.

Eu prefiro deixar a estrutura feia temporariamente e construir um mapa confiável.

Depois, reorganizar deixa de ser aposta.

Critério de liberação #

Um modelo simples de gate para um template liberado a operadores:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[ ] finalidade clara
[ ] inventory conhecido
[ ] variáveis conhecidas
[ ] secrets fora do Git
[ ] risco classificado
[ ] testado por responsável técnico
[ ] nome e descrição claros
[ ] Survey definido
[ ] proteção quando altera estado
[ ] validação pós-execução

Playbooks HIGH/DANGER merecem regras adicionais e, em muitos ambientes, devem permanecer restritos.

O que a fonte sustenta #

A plataforma privada analisada documenta:

• inventário preliminar de dezenas de playbooks;
• classificação LOW/MEDIUM/HIGH/DANGER/UNKNOWN;
• categorias operacionais;
• campos de análise por playbook;
• política de não reorganizar antes da leitura;
• seleção inicial de templates LOW;
• padrão de Survey Variables;
• operadores Task Runner;
• critérios para liberação de templates.

O artigo não afirma que todos os playbooks já foram convertidos ou classificados definitivamente.

O principal aprendizado #

Semaphore não resolve desorganização só porque adiciona uma interface web.

O valor aparece quando o orquestrador vira uma camada de contrato, permissão e contexto sobre automações que primeiro foram entendidas.

A sequência que funcionou melhor foi:

1
2
3
4
5
6
7

inventariar
→ entender
→ classificar risco
→ definir contrato
→ testar
→ liberar
→ só depois reorganizar

Automação segura começa antes do botão “Run”.