# Nexus Infrastructure Framework: Multi-Cluster OKE & Data Services

## 1. Overview e Propósito

Este framework de **Infraestrutura como Código (IaC)** foi desenvolvido para provisionar e gerir um ecossistema complexo na **Oracle Cloud Infrastructure (OCI)**. O seu propósito central é a orquestração de múltiplos clusters de Kubernetes (OKE) — denominados **Nexus**, **Bus** e **Observability** — de forma modular e altamente automatizada.

O projeto elimina a configuração manual ao integrar nativamente serviços de base de dados (SQL, NoSQL e Cache) com uma camada de segurança centralizada em **OCI Vault**, garantindo que a infraestrutura seja entregue em estado "ready-to-use" para equipes de desenvolvimento.

---

## 2. Resumo de Funcionamento (Workflow)

O funcionamento da stack baseia-se num ciclo de vida de **quatro fases de execução**, garantindo que as dependências de rede e segurança sejam resolvidas antes do provisionamento das aplicações:

1. **Fase de Descoberta e Rede:** O script consome uma VCN existente e utiliza funções de manipulação de strings e regex para validar e provisionar subnets regionais segregadas (API, Nodes, Pods e Load Balancers) para cada cluster ativado.

2. **Provisionamento de Hardware:** O módulo `oke_cluster` utiliza a arquitetura **Enhanced Cluster**. A lógica interna (`locals.tf`) identifica automaticamente a imagem de SO mais recente e compatível com o processador escolhido (AMD x86_64 ou ARM aarch64).

3. **Bootstrap de Identidade (Mecanismo de Escada):** Para evitar erros de sincronização (Race Conditions), o script implementa um timer de estabilização. Após este período, o provedor Kubernetes configura o RBAC e gera os tokens de acesso.

4. **Consolidação de Segredos:** Todas as credenciais geradas (senhas de DB, tokens K8s, endpoints) são injetadas no **OCI Vault (KMS)**, protegendo os dados sensíveis contra exposição em logs ou no estado do Terraform.

---

## 3. Processos, Funções e Módulos Detalhados

### 📦 Módulo: `oke_cluster` (Infraestrutura de Base)

* **Função:** Abstrair a complexidade da rede nativa e provisionamento de nós.
* **Mecanismo:** Implementa o CNI `OCI_VCN_IP_NATIVE`. Isto permite que cada Pod receba um IP real da VCN, eliminando a sobrecarga de NAT e garantindo performance de rede idêntica a instâncias Bare Metal.
* **Gestão de Imagens:** Utiliza filtros dinâmicos que cruzam a versão do Kubernetes desejada com a disponibilidade de imagens na região, garantindo sempre o uso de patches de segurança atualizados.

### 🛡️ Módulo: `oke_bootstrap` (Configuração de Identidade)

* **Função:** Configurar o acesso administrativo interno e integração de CI/CD.
* **Mecanismo de Escada:** Utiliza o recurso `time_sleep` para aguardar 120 segundos após a criação do cluster. Só então procede à criação da `ServiceAccount` (`cicd-admin-sa`) e do `ClusterRoleBinding`.
* **Saída Segura:** Extrai o token de autenticação do Kubernetes e armazena-o no Vault, permitindo que ferramentas externas consumam o cluster sem necessidade de intervenção manual.

### 🗄️ Camada de Serviços de Dados (`postgresql`, `redis`, `autonomous`)

* **Função:** Provisionar persistência com isolamento de rede.
* **Roteamento:** Configura **Service Gateways** e **NAT Gateways** dedicados. Os bancos de dados residem em subnets privadas, comunicando-se com o Object Storage da Oracle para backups através da rede interna da Oracle, sem exposição à internet.

---

## 4. UI do Resource Manager (ORM): Flexibilidade e Controle

A interface visual definida no `schema.yaml` atua como um **motor de validação e governação** para o utilizador final.

### Funcionalidades da Interface:

* **Visibilidade Dinâmica:** Através de regras `visible: eq:`, a interface oculta automaticamente grupos de variáveis de clusters que não foram marcados como ativos, reduzindo a complexidade do formulário.
* **Validação de CIDR e OCID:** Implementação de `pattern` (Regex) em campos críticos. Isto garante que o utilizador não submeta a stack com erros de sintaxe em endereços de rede ou IDs de compartimento, prevenindo falhas tardias no deploy.
* **Controlo Flexível de Shapes (AMD vs Intel):**
  * O formulário deteta a arquitetura do shape escolhido.
  * **Limites Adaptativos:** Se o utilizador selecionar um shape Intel (Standard3), a UI ajusta o mínimo de oCPUs para 2. Se selecionar AMD (E5/E6), permite o mínimo de 1 oCPU, respeitando as restrições físicas do hardware Oracle.
* **Segurança de Confirmação:** Atributos de `confirmation: true` em campos de rede e passwords obrigam à dupla digitação, mitigando erros humanos em infraestruturas críticas.

---

## 5. Resumo Técnico de Serviços e Ficheiros

| Serviço | Ficheiro | Função Técnica Principal |
| :--- | :--- | :--- |
| **KMS / Vault** | `vault.tf` | Gestão de chaves AES-256 e encriptação de segredos. |
| **PostgreSQL** | `postgresql.tf` | DB Gerenciado com rotação de passwords via `random_password`. |
| **Redis** | `redis.tf` | Cache distribuído em cluster com persistência privada. |
| **Object Storage**| `bucket.tf` | Buckets com versionamento para armazenamento de logs e artefatos. |
| **OKE** | `oke_cluster.tf` | Orquestração de containers com suporte a IP Native e Auto-scaling. |

---

## 🛠️ Como Utilizar

1. Comprima todos os ficheiros `.tf` e o `.yaml` num arquivo `.zip`.
2. No console OCI, aceda a **Developer Services > Resource Manager > Stacks**.
3. Faça o upload do arquivo zip.
4. Configure os parâmetros através da UI customizada e execute **Plan** & **Apply**.

---

* Documentação gerada para a Nexus Infrastructure Stack - Março 2026*