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

Ordem de Implantação do Supabase Auto-HospedadoOs 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

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`

Get Started!

Offerings

Chat

Agents

Knowledge Base

Workflows

Public Chatbot

Project Settings

My Account

Platform Admin

SDK

General Information

Change Logs

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)

​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)

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)