Infraestrutura Terraform do EKB

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	Guia passo a passo para criar e implantar um novo ambiente
Visão Geral da Arquitetura AWS	Visão geral da arquitetura, descrições dos componentes e fluxo de dados
Estratégia de Recuperação de Desastres	Estratégia de DR, objetivos RTO/RPO, sistemas de backup e procedimentos de recuperação
Lista de Verificação de Pré-requisitos	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

# macOS
brew install terraform

# Linux
sudo apt update && sudo apt install terraform

Terragrunt

# 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

# 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

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 para o processo completo passo a passo. O fluxo de alto nível é:

# 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

Informação

Ordem de Implantação do Supabase Auto-Hospedado

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

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"]'

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:

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

aviso

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.

Solução de Problemas

Verificar credenciais AWS

aws sts get-caller-identity

Verificar acesso ao cluster

aws eks update-kubeconfig --region <regiao> --name <nome-do-cluster>
kubectl get nodes
kubectl get pods -A

Verificar o Controlador ALB

kubectl get pods -n infrastructure | grep aws-load-balancer-controller
kubectl get ingress -A

Verificar o Karpenter

kubectl get pods -n kube-system | grep karpenter
kubectl get nodepools
kubectl get nodeclaims

Verificar lock de estado

# 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

grep -r "<YOUR_" terragrunt/environments/nome-do-seu-ambiente/

Verificar status da release Helm

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`

Documentação​

Estrutura do Repositório​

Início Rápido​

1. Instale as Ferramentas Necessárias​

2. Crie um Novo Ambiente​

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

Referência de Charts Helm​

Referência de Módulos​

modules/eks​

modules/aws-services​

modules/state​

modules/helm​

Configuração do Ambiente​

Placeholders​

Estado Remoto​

Segredos​

Solução de Problemas​

Suporte Multi-Cloud (Planejado)​