Por que eu não reorganizo um repositório Ansible antes de inventariar os playbooks

Repositório Ansible antigo costuma incomodar visualmente.

Arquivos crescem na raiz, aparecem nomes inconsistentes, cópias de teste, versões “rápido”, scripts que parecem duplicados e pastas que ninguém mais lembra por que existem.

A vontade natural é começar pela limpeza:

1
2
3
4

playbooks/
roles/
tasks/
legacy/

No projeto que originou este artigo, a regra foi explicitamente o contrário:

não reorganizar fisicamente os playbooks antes da análise.

Essa decisão evita transformar uma auditoria em uma migração simultânea.

Estrutura feia ainda pode ser uma estrutura conhecida #

Um arquivo pode ter um nome ruim e estar referenciado por:

• Semaphore;
• cron;
• CI/CD;
• documentação;
• script shell;
• operador acostumado ao caminho;
• include/import em outro playbook.

Mover o arquivo para “organizar” pode quebrar uma dependência que ainda não foi descoberta.

Primeiro eu quero mapear o estado atual.

O inventário inicial pode ser imperfeito #

A documentação real criou uma tabela com campos como:

1
2
3
4
5
6
7
8
9

arquivo
ativo?
categoria preliminar
risco preliminar
inventory
variáveis
secrets
template sugerido
status

Várias células começaram como:

1
2
3
4

desconhecido
a mapear
UNKNOWN
pendente

Isso não é falha do inventário.

É exatamente o que a auditoria precisava tornar explícito.

“Ativo” e “existe no Git” são coisas diferentes #

Um playbook pode estar no repositório e não ser usado há anos.

Outro pode ser usado diariamente mesmo com nome de teste.

Para classificar atividade, eu procuraria evidências como:

• template Semaphore apontando para ele;
• histórico recente de execução;
• referência em runbook;
• commit recente ligado a operação;
• cron/script chamando o arquivo;
• confirmação operacional de quem usa.

Sem isso, ativo? = desconhecido é uma resposta válida.

Duplicidade precisa de leitura #

Arquivos como:

1
2
3

atualiza_app.yml
atualiza_app_rapido.yml
atualiza_app_rapido-teste.yml

parecem uma família.

Mas podem representar:

• versões antigas;
• fluxos diferentes;
• wrappers;
• testes abandonados;
• playbooks ativos para ambientes diferentes.

Antes de deletar ou consolidar, comparar:

1
2
3
4
5
6
7
8

hosts
vars
roles/tasks
handlers
shell/command
condições
tags
rollback

A semelhança do nome é só ponto de partida.

Classificação por finalidade vem antes da nova árvore de pastas #

Na auditoria, os playbooks foram agrupados conceitualmente em áreas 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

Isso permite descobrir qual organização faria sentido depois.

Talvez a futura estrutura seja por domínio técnico.

Talvez por projeto.

Talvez playbooks fiquem simples e roles concentrem a reutilização.

Sem classificação, criar pastas é escolher taxonomia antes de conhecer o acervo.

Também é preciso mapear inputs #

Mover um playbook é a parte fácil.

Mais importante é saber o contrato dele:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

inventory esperado
limit
grupo/host
vars obrigatórias
vars opcionais
Variable Group
secrets
arquivos auxiliares
roles/collections
CLI externa

Um playbook que depende de AWS CLI e outro que depende de kubectl podem estar lado a lado, mas precisam de ambientes de execução diferentes ou de um executor que contenha ambos.

Risco deve entrar no inventário antes da refatoração #

Imagine descobrir depois da mudança de estrutura que o arquivo movido para uma pasta genérica maintenance/ faz:

1

restart em produção

A organização ideal deveria tornar o risco visível também no catálogo de execução, não apenas no path.

Por isso a plataforma usa LOW/MEDIUM/HIGH/DANGER/UNKNOWN durante a análise.

O primeiro alvo de melhoria deve ser o caminho seguro #

Em vez de começar refatorando deploys críticos, eu gosto de pegar playbooks LOW:

• smoke;
• ping;
• facts;
• health check;
• leitura de logs;
• inventário.

Eles permitem validar:

1
2
3
4
5
6
7

novo template
novo inventory
chaves
executor
Survey
logs
permissões

sem testar a nova governança num restart real.

Refatoração pode vir em fases #

Um caminho mais previsível:

Fase 1 — inventário #

Nada é movido.

Fase 2 — classificação #

Ativo/legado/duplicado/desconhecido, categoria e risco.

Fase 3 — contratos #

Inventory, vars, secrets, dependências, resultado esperado.

Fase 4 — templates #

Publicar primeiro operações LOW e depois mudanças controladas.

Fase 5 — consolidação #

Só agora decidir:

• renomear;
• mover;
• extrair role;
• remover duplicado;
• arquivar legado.

Fase 6 — limpeza #

Depois que referências externas também forem ajustadas.

O histórico continua útil #

Um repositório operacional não é apenas produto final.

Ele conta como a operação evoluiu.

Antes de remover uma versão aparentemente antiga, vale entender se ela explica:

• uma migração;
• uma exceção;
• um rollback;
• uma diferença de ambiente.

Nem tudo precisa permanecer para sempre, mas deletar antes de entender elimina contexto.

O que a fonte sustenta #

A documentação privada analisada instrui explicitamente:

• não reorganizar fisicamente os playbooks antes da análise;
• classificar em lotes;
• identificar ativos, legados, duplicados e desconhecidos;
• mapear risco, inventory, variáveis, secrets e dependências;
• priorizar candidatos LOW para templates;
• só depois considerar reorganização.

O artigo transforma essa regra em método de trabalho sem afirmar que toda a reorganização final já ocorreu.

O principal aprendizado #

Organização visual é uma otimização de segunda ordem.

Num repositório de automação de produção, a primeira pergunta é:

o que este arquivo faz, quem depende dele e qual é o risco de executá-lo?

Quando isso está respondido, mover arquivos deixa de ser limpeza por intuição e vira uma mudança planejada.