Ansible vSphere Template

Template publico para automacao Ansible em ambientes VMware vSphere, com inventario multiambiente, execucao padronizada por Makefile/deploy.sh, uso opcional de Ansible Vault, CI de qualidade e documentacao pronta para TechDocs.

Este repositorio foi preparado para portfolio DevOps/SRE: exemplos sem dados internos, validacoes reproduziveis, checks contra secrets, runbooks e estrutura pronta para projetos derivados.

Objetivo

Este repositório não representa uma automação final para um serviço específico. Ele entrega uma estrutura pública e reutilizável para iniciar novos projetos Ansible com separação clara entre inventário, variáveis, playbooks, roles, runbooks e documentação.

O Que Este Projeto Demonstra

• Automacao Ansible organizada por inventario, group_vars, playbooks e roles.
• Modelo multiambiente para dev, homolog e prod com IPs reservados para documentacao publica.
• Fluxo operacional por Makefile e deploy.sh, com suporte a --check, verbosidade, Vault e confirmacao interativa.
• Higiene publica: .gitignore, checks contra secrets/chaves/logs e varredura de marcadores internos.
• Qualidade continua: yamllint, ansible-inventory, ansible-playbook --syntax-check, ansible-lint, Trivy e TechDocs no GitHub Actions.
• Documentacao operacional em docs/ e runbooks/, com evidencias reproduziveis em docs/evidence.md.

Arquitetura Operacional

operator
  |
  |  make deploy-dev | ./deploy.sh --limit dev --check
  v
Ansible control node
  |
  |-- ansible.cfg                -> defaults, paths e logging local
  |-- inventories/inventory.yml  -> grupos dev/homolog/prod
  |-- group_vars/                -> variaveis globais e por ambiente
  |-- roles/requirements.yml     -> roles/collections externas
  |-- playbooks/deploy.yml       -> orquestracao principal
  v
VMware vSphere VMs
  |
  |-- hosts Linux acessados por SSH
  |-- sudo/become conforme politica do ambiente
  |-- secrets fora do Git via Vault ou variaveis de ambiente

Validacao Rapida

python3 -m pip install --user -r requirements-dev.txt
make validate
make security-check
make techdocs

O make validate cobre YAML, inventario, syntax-check, ansible-lint e checks publicos. O CI executa o mesmo contrato de forma estrita em pull requests e pushes para main.

O que já vem pronto

• Inventário de exemplo para dev, homolog e prod usando ranges reservados para documentação.
• Makefile com comandos para instalação de dependências, validação de inventário, sintaxe, lint, checks públicos e deploy por ambiente.
• deploy.sh com validações, seleção de ambiente, modo check e suporte opcional a Vault por variável de ambiente.
• GitHub Actions com validação Ansible, lint, Trivy, TechDocs e checks contra publicação acidental de material sensível.
• roles/requirements.yml preparado para declarar dependências externas.
• catalog-info.yaml e mkdocs.yml para publicação via Backstage TechDocs.
• Diretórios separados para documentação, runbooks, logs e chaves SSH.

Segurança

Este template não deve armazenar segredos reais. Os arquivos versionados usam valores de exemplo e endereços reservados. Ao derivar um projeto real:

• mantenha senhas, tokens e chaves privadas fora do Git;
• use Ansible Vault para variáveis sensíveis;
• prefira ANSIBLE_VAULT_PASSWORD_FILE apontando para um arquivo fora do repositório quando precisar executar playbooks com Vault;
• revise inventário e variáveis antes de publicar qualquer projeto derivado.

Fluxo rápido

Pré-requisitos

• Python 3.12 para reproduzir o CI localmente
• Ansible Core 2.21.x
• Git
• Make

Instalação recomendada das ferramentas de validação:

python3 -m pip install --user -r requirements-dev.txt

Comandos principais

# Instalar roles e collections quando forem declaradas
make install-roles

# Validar sintaxe do playbook
make syntax

# Validação sem conectar nos hosts de exemplo
make test

# Deploy por ambiente
make deploy-dev
make deploy-homolog
make deploy-prod

Ou com o script principal:

./deploy.sh --limit dev --check
./deploy.sh --limit homolog
./deploy.sh --limit prod --verbose 2

Se o projeto derivado usar Vault:

export ANSIBLE_VAULT_PASSWORD_FILE="$HOME/.ansible/vault-pass.txt"
make syntax VAULT_OPTS="--vault-password-file $ANSIBLE_VAULT_PASSWORD_FILE"

Estrutura principal

ansible-vsphere-template/
├── docs/
├── group_vars/
├── inventories/
├── logs/
├── playbooks/
├── roles/
├── runbooks/
├── scripts/
├── ssh/
├── ansible.cfg
├── catalog-info.yaml
├── deploy.sh
├── Makefile
└── mkdocs.yml

Como usar este repositório como template

1. Crie um novo repositório derivado desta base.
2. Ajuste README.md, catalog-info.yaml, mkdocs.yml e a documentação para o novo contexto.
3. Substitua hosts, grupos, portas, usuários e variáveis de exemplo.
4. Defina as roles realmente necessárias em roles/requirements.yml.
5. Mova qualquer segredo para arquivos de Vault não versionados.
6. Valide make validate, make security-check e make techdocs antes de publicar.

Documentação

• Documentação técnica para o portal: docs/
• Runbooks operacionais: runbooks/
• Guia de contribuição: CONTRIBUTING.md
• Política de segurança: SECURITY.md
• Histórico de mudanças: CHANGELOG.md
• Evidências de validação: docs/evidence.md

Referências

• TechDocs local
• Guia de chaves SSH
• Runbooks operacionais
• Documentação do Ansible