> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Infraestrutura Terraform do EKB

> IaC Terraform e Terragrunt para gerenciar a plataforma EKB no AWS EKS, com suporte preliminar para GKE, AKS e Kubernetes bare-metal.

Este artigo contém a infraestrutura como código (IaC) Terraform e Terragrunt para gerenciar a plataforma EKB no AWS EKS, com suporte preliminar para GKE, AKS e Kubernetes bare-metal. Ele inclui todas as implantações de charts Helm e templates de configuração de ambiente.

***

## Documentação

| Documento                                                                                                          | Descrição                                                                              |
| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| [Guia de Implantação Terragrunt](/offerings/on-premise/kubernetes-deployment/terragrunt-deployment)                | Guia passo a passo para criar e implantar um novo ambiente                             |
| [Visão Geral da Arquitetura AWS](/offerings/on-premise/kubernetes-deployment/aws-architecture)                     | Visão geral da arquitetura, descrições dos componentes e fluxo de dados                |
| [Estratégia de Recuperação de Desastres](/offerings/on-premise/kubernetes-deployment/disaster-recovery-guide)      | Estratégia de DR, objetivos RTO/RPO, sistemas de backup e procedimentos de recuperação |
| [Lista de Verificação de Pré-requisitos](/offerings/on-premise/kubernetes-deployment/eks-deployment-prerequisites) | Lista de verificação pré-implantação para completar com o cliente                      |

***

## Estrutura do Repositório

```
ekb-terraform/
├── root.hcl                              # Configuração raiz do Terragrunt (estado remoto, geração de provider)
│
├── modules/                              # Módulos Terraform reutilizáveis
│   ├── eks/                              # Cluster AWS EKS, VPC, Karpenter, IAM, releases Helm
│   ├── aws-services/                     # ElastiCache Redis, Amazon MQ RabbitMQ
│   ├── helm/                             # Módulo genérico de release Helm
│   ├── state/                            # Inicialização do bucket de estado S3
│   ├── aks/                              # Azure AKS (preliminar)
│   ├── gke/                              # Google GKE (preliminar)
│   └── baremetal/                        # Kubernetes bare-metal (preliminar)
│
├── terragrunt/
│   ├── .gitignore
│   └── environments/
│       ├── STATE_MANAGEMENT_README.md
│       └── env-template-folder/          # Template para novos ambientes — copie e preencha os placeholders
│           ├── terragrunt.hcl            # Configuração principal do ambiente (cluster, releases Helm, serviços AWS)
│           ├── state/
│           │   └── terragrunt.hcl        # Inicialização do bucket de estado para este ambiente
│           └── values/                   # Valores Helm por chart (um arquivo por chart)
│               ├── infrastructure.yaml       # AWS Load Balancer Controller
│               ├── aws-ebs-csi-driver.yaml   # EBS CSI Driver
│               ├── karpenter.yaml            # Karpenter NodePool
│               ├── karpenter-nodeclasses.yaml# Karpenter EC2NodeClass
│               ├── karpenter-values.yaml     # Valores do controlador Karpenter
│               ├── keda.yaml                 # Escalonador KEDA
│               ├── odin-services.yaml        # Serviços de aplicação EKB
│               ├── cloudnative-pg.yaml       # Operador CloudNativePG (ENABLE_CNPG)
│               ├── ha-supabase-db.yaml       # Cluster HA Postgres via CNPG (ENABLE_HA_SUPABASE_DB)
│               ├── supabase.yaml             # Pilha de aplicação Supabase (ENABLE_SUPABASE)
│               ├── signoz.yaml               # Plataforma de observabilidade SigNoz (ENABLE_SIGNOZ)
│               └── signoz-k8s-infra.yaml     # Agente de métricas k8s-infra do SigNoz (ENABLE_SIGNOZ)
│
└── helm-deployment/                      # Charts Helm locais/vendored
    ├── infrastructure/                   # Chart wrapper do ALB Controller
    ├── odin-services/odin-services/      # Plataforma EKB (Web, API, Celery, Automator, Ingress)
    ├── cloudnative-pg/                   # Chart do operador CloudNativePG
    ├── ha-supabase-db/                   # HA Supabase DB (Cluster CNPG + PgBouncer + backups barman)
    ├── supabase-kubernetes-ha/           # Pilha completa de aplicação Supabase
    ├── signoz/                           # Plataforma de observabilidade SigNoz
    └── k8s-infra/                        # Agente de métricas do cluster k8s-infra do SigNoz
```

***

## Início Rápido

### 1. Instale as Ferramentas Necessárias

**Terraform**

```bash theme={null}
# macOS
brew install terraform

# Linux
sudo apt update && sudo apt install terraform
```

**Terragrunt**

```bash theme={null}
# macOS
brew install terragrunt

# Linux / macOS (manual)
curl -Lo /usr/local/bin/terragrunt \
  https://github.com/gruntwork-io/terragrunt/releases/latest/download/terragrunt_linux_amd64
chmod +x /usr/local/bin/terragrunt
```

**kubectl e Helm**

```bash theme={null}
# macOS
brew install kubectl helm

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -m 0755 kubectl /usr/local/bin/kubectl
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
```

**Verificar instalação**

```bash theme={null}
terraform --version
terragrunt --version
kubectl version --client
helm version
aws sts get-caller-identity
```

***

### 2. Crie um Novo Ambiente

Novos ambientes são criados copiando `env-template-folder` e preenchendo os placeholders.

Consulte o [Guia de Implantação Terragrunt](/offerings/on-premise/kubernetes-deployment/terragrunt-deployment) para o processo completo passo a passo. O fluxo de alto nível é:

```bash theme={null}
# 1. Copie o template
cp -r terragrunt/environments/env-template-folder terragrunt/environments/nome-do-seu-ambiente

# 2. Preencha todos os placeholders <YOUR_*> em:
#    - terragrunt/environments/nome-do-seu-ambiente/terragrunt.hcl
#    - terragrunt/environments/nome-do-seu-ambiente/state/terragrunt.hcl
#    - terragrunt/environments/nome-do-seu-ambiente/values/*.yaml

# 3. Inicialize o bucket de estado
cd terragrunt/environments/nome-do-seu-ambiente/state
terragrunt apply

# 4. Defina as variáveis de ambiente e implante
cd ../
export ENABLE_ALB_CONTROLLER=true
export WEB_DOMAIN="app.example.com"
export WEB_CERTIFICATE_ARN="arn:aws:acm:<regiao>:<conta>:certificate/<id>"
# ... (veja TERRAGRUNT_DEPLOYMENT_GUIDE.md para a lista completa de variáveis)

terragrunt apply
```

***

## Flags de Habilitação/Desabilitação de Serviços

Todos os serviços opcionais são alternados via variáveis de ambiente. Defina-as antes de executar `terragrunt apply`.

| Variável                | Padrão  | Serviço                                                          |
| ----------------------- | ------- | ---------------------------------------------------------------- |
| `ENABLE_ALB_CONTROLLER` | `true`  | AWS Load Balancer Controller                                     |
| `ENABLE_AWS_SERVICES`   | `false` | ElastiCache Redis + Amazon MQ RabbitMQ                           |
| `ENABLE_CNPG`           | `false` | Operador CloudNativePG                                           |
| `ENABLE_HA_SUPABASE_DB` | `false` | Cluster PostgreSQL HA (requer `ENABLE_CNPG=true`)                |
| `ENABLE_SUPABASE`       | `false` | Pilha completa do Supabase (requer `ENABLE_HA_SUPABASE_DB=true`) |
| `ENABLE_SIGNOZ`         | `false` | Observabilidade SigNoz + agente k8s-infra                        |

<Info>
  **Ordem de Implantação do Supabase Auto-Hospedado**

  Os componentes do Supabase devem ser implantados em sequência:

  ```bash theme={null}
  ENABLE_CNPG=true           terragrunt apply --target='helm_release.local["cloudnative-pg"]'
  ENABLE_HA_SUPABASE_DB=true terragrunt apply --target='helm_release.local["ha-supabase-db"]'
  ENABLE_SUPABASE=true       terragrunt apply --target='helm_release.local["supabase"]'
  ```
</Info>

***

## Referência de Charts Helm

| Chart (em `helm-deployment/`)   | Namespace        | Habilitado por          | Descrição                                |
| ------------------------------- | ---------------- | ----------------------- | ---------------------------------------- |
| `infrastructure`                | `infrastructure` | Sempre                  | AWS Load Balancer Controller             |
| `odin-services/odin-services`   | `default`        | Sempre                  | Web, FastAPI, Celery, Automator, Ingress |
| `aws-ebs-csi-driver` (upstream) | `kube-system`    | Sempre                  | Driver de volume persistente EBS         |
| `keda` (upstream)               | `keda`           | Sempre                  | Escalonamento automático de pods         |
| `cloudnative-pg`                | `cnpg-system`    | `ENABLE_CNPG`           | Operador PostgreSQL                      |
| `ha-supabase-db`                | `ha-supabase-db` | `ENABLE_HA_SUPABASE_DB` | HA Postgres + PgBouncer + backups barman |
| `supabase-kubernetes-ha`        | `supabase`       | `ENABLE_SUPABASE`       | Kong, Auth, Storage, Studio, Realtime    |
| `signoz`                        | `monitoring`     | `ENABLE_SIGNOZ`         | Rastreamento distribuído, métricas, logs |
| `k8s-infra` (upstream)          | `monitoring`     | `ENABLE_SIGNOZ`         | Agente DaemonSet de métricas do cluster  |

***

## Referência de Módulos

### `modules/eks`

O módulo principal. Provisiona:

* VPC com sub-redes públicas/privadas em 3 AZs
* Cluster EKS (Kubernetes 1.33) e node group gerenciado para Karpenter
* Controlador Karpenter + NodePool + EC2NodeClass
* Funções IAM (cluster, node group, Karpenter, controlador ALB, EBS CSI driver)
* Todas as releases Helm via o mapa de entrada `helm_releases`

### `modules/aws-services`

Provisiona ElastiCache Redis e Amazon MQ RabbitMQ. Somente ativo quando `ENABLE_AWS_SERVICES=true`.

### `modules/state`

Inicializa o bucket de estado S3 para um novo ambiente (versionamento, criptografia, bloqueio de acesso público).

### `modules/helm`

Módulo de release Helm reutilizável suportando tanto repositórios de chart upstream quanto charts locais com `chart_path`.

***

## Configuração do Ambiente

### Placeholders

Cada valor em `env-template-folder` que é específico do ambiente usa um placeholder `<YOUR_*>`. Execute o seguinte para verificar se nada foi esquecido antes de implantar:

```bash theme={null}
grep -r "<YOUR_" terragrunt/environments/nome-do-seu-ambiente/
```

### Estado Remoto

O estado é armazenado no S3 por ambiente. O bucket é inicializado por `state/terragrunt.hcl` e referenciado por `root.hcl`. O padrão de nomenclatura é `ekb-terraform-state-<nome-do-ambiente>`.

### Segredos

<Warning>
  Valores sensíveis (senhas, chaves de API, ARNs de certificados) **nunca são commitados**. Eles são passados como variáveis de ambiente consumidas por chamadas `get_env()` em `terragrunt.hcl`, ou como placeholders `<YOUR_*>` em arquivos de valores que devem ser preenchidos antes da implantação.
</Warning>

***

## Solução de Problemas

**Verificar credenciais AWS**

```bash theme={null}
aws sts get-caller-identity
```

**Verificar acesso ao cluster**

```bash theme={null}
aws eks update-kubeconfig --region <regiao> --name <nome-do-cluster>
kubectl get nodes
kubectl get pods -A
```

**Verificar o Controlador ALB**

```bash theme={null}
kubectl get pods -n infrastructure | grep aws-load-balancer-controller
kubectl get ingress -A
```

**Verificar o Karpenter**

```bash theme={null}
kubectl get pods -n kube-system | grep karpenter
kubectl get nodepools
kubectl get nodeclaims
```

**Verificar lock de estado**

```bash theme={null}
# Desbloquear forçadamente um estado travado (use o ID do lock da mensagem de erro)
cd terragrunt/environments/nome-do-seu-ambiente
terragrunt force-unlock <lock-id>
```

**Verificar se não há placeholders restantes**

```bash theme={null}
grep -r "<YOUR_" terragrunt/environments/nome-do-seu-ambiente/
```

**Verificar status da release Helm**

```bash theme={null}
helm list -A
helm status <release-name> -n <namespace>
helm get values <release-name> -n <namespace>
```

***

## Suporte Multi-Cloud (Planejado)

| Plataforma | Status     | Módulo              |
| ---------- | ---------- | ------------------- |
| AWS EKS    | Ativo      | `modules/eks`       |
| Azure AKS  | Preliminar | `modules/aks`       |
| Google GKE | Preliminar | `modules/gke`       |
| Bare metal | Preliminar | `modules/baremetal` |