# Estrutura e Automações

## Estrutura do repositório

A estrutura do repositório segue o seguinte formato:

```
infra/
├── clusters/           # Um diretório por cluster Kubernetes
│   └── admin/          # Cluster admin (Terraform + Terragrunt)
├── modules/            # Módulos Terraform reutilizáveis
│   ├── vsphere-vm/     # Provisionamento de VM no vSphere
│   ├── k3s-cluster/    # Cluster k3s completo
│   ├── k3s-server/     # Nó servidor k3s
│   └── k3s-agent/      # Nó agente k3s
├── ansible/            # Playbooks de pós-configuração
│   ├── site.yml        # Configura clusters k8s (addons, discos, etc)
│   └── edge.yml        # Configura VMs de borda (nginx, firewall)
└── .gitlab-ci.yml      # Pipeline de CI
```

Cada diretório em `clusters/` é um módulo Terragrunt que referencia os módulos reutilizáveis de `modules/`. O estado do terraform está sendo salvo no próprio GitLab. Desse modo, todos os comandos do terraform devem ser executados diretamente pelo GitLab CI ou utilizando o estado remoto do GitLab.

---

## Nomenclatura de branches neste repositório

| Prefixo | Exemplo |
|---|---|
| `feat/` | `feat/cluster-portal` |
| `upgrade/` | `upgrade/k3s-1.32`, `upgrade/terraform-1.10` |
| `fix/` | `fix/rede-admin`, `fix/disco-node1` |
| `resize/` | `resize/admin-node1-memoria`, `resize/portal-node2-cpu` |
| `docs/` | `docs/tutorial-novo-cluster` |

---

## Pipeline de CI

O pipeline possui quatro stages executados em sequência:

```
validate ──► plan ──► apply ──► configure
```

| Stage | Quando roda | O que faz |
|---|---|---|
| `validate` | Todo push e todo MR | Valida a sintaxe dos arquivos Terraform |
| `plan` | Todo push e todo MR | Mostra o que seria criado, alterado ou destruído |
| `apply` | Somente na `main`, **manual** | Aplica as mudanças de infraestrutura no vSphere |
| `configure` | Somente na `main`, automático após apply | Roda Ansible para configurar k8s e VMs de borda |

O `apply` **nunca roda sozinho** — exige um clique manual de quem aprovou o MR. O `configure` roda automaticamente em seguida, se o `apply` for bem-sucedido.

---

## Variáveis de CI necessárias

Configuradas no grupo `dicom` do GitLab (Settings → CI/CD → Variables):

| Variável | Descrição |
|---|---|
| `VSPHERE_PASSWORD` | Senha do usuário de serviço no vSphere |
| `ANSIBLE_SSH_PUBLIC_KEY` | Chave pública SSH injetada nas VMs pelo Terraform |
| `ANSIBLE_SSH_PRIVATE_KEY` | Chave privada SSH usada pelo Ansible (em base64) |
| `CERT_MANAGER_TSIG_SECRET` | Chave TSIG para desafios DNS01 do cert-manager (Obsoleto: está sendo movido para repositório `stacks`) |

---