Infraestructura Terraform de EKB

Este artículo contiene la infraestructura como código (IaC) de Terraform y Terragrunt para gestionar la plataforma EKB en AWS EKS, con módulos de soporte para GKE, AKS y Kubernetes bare-metal. Incluye todos los despliegues de charts Helm y plantillas de configuración de entornos.

Documentación

Documento	Descripción
Guía de Despliegue con Terragrunt	Guía paso a paso para crear y desplegar un nuevo entorno
Descripción General de la Arquitectura AWS	Descripción general de la arquitectura, componentes y flujo de datos
Estrategia de Recuperación ante Desastres	Estrategia DR, objetivos RTO/RPO, sistemas de respaldo y procedimientos de recuperación
Lista de Prerrequisitos	Lista de verificación previa al despliegue para completar con el cliente

Estructura del Repositorio

ekb-terraform/
├── root.hcl                              # Configuración raíz de Terragrunt (estado remoto, generación de provider)
│
├── modules/                              # Módulos Terraform reutilizables
│   ├── eks/                              # Cluster EKS de AWS, VPC, Karpenter, IAM, releases de Helm
│   ├── aws-services/                     # ElastiCache Redis, Amazon MQ RabbitMQ
│   ├── helm/                             # Módulo genérico de release Helm
│   ├── state/                            # Bootstrap del bucket de estado S3
│   ├── aks/                              # Azure AKS (módulo)
│   ├── gke/                              # Google GKE (módulo)
│   └── baremetal/                        # Kubernetes bare-metal (módulo)
│
├── terragrunt/
│   ├── .gitignore
│   └── environments/
│       ├── STATE_MANAGEMENT_README.md
│       └── env-template-folder/          # Plantilla para nuevos entornos — copiar y completar placeholders
│           ├── terragrunt.hcl            # Configuración principal del entorno (cluster, releases Helm, servicios AWS)
│           ├── state/
│           │   └── terragrunt.hcl        # Bootstrap del bucket de estado para este entorno
│           └── values/                   # Valores Helm por chart (un archivo 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 del controlador Karpenter
│               ├── keda.yaml                 # KEDA autoscaler
│               ├── odin-services.yaml        # Servicios de aplicación EKB
│               ├── cloudnative-pg.yaml       # Operador CloudNativePG (ENABLE_CNPG)
│               ├── ha-supabase-db.yaml       # Cluster HA Postgres vía CNPG (ENABLE_HA_SUPABASE_DB)
│               ├── supabase.yaml             # Stack de aplicación Supabase (ENABLE_SUPABASE)
│               ├── signoz.yaml               # Plataforma de observabilidad SigNoz (ENABLE_SIGNOZ)
│               └── signoz-k8s-infra.yaml     # Agente de métricas k8s-infra de SigNoz (ENABLE_SIGNOZ)
│
└── helm-deployment/                      # Charts Helm locales
    ├── infrastructure/                   # Chart wrapper del ALB Controller
    ├── odin-services/odin-services/      # Plataforma EKB (Web, API, Celery, Automator, Ingress)
    ├── cloudnative-pg/                   # Chart del operador CloudNativePG
    ├── ha-supabase-db/                   # DB HA de Supabase (Cluster CNPG + PgBouncer + respaldos barman)
    ├── supabase-kubernetes-ha/           # Stack completo de aplicación Supabase
    ├── signoz/                           # Plataforma de observabilidad SigNoz
    └── k8s-infra/                        # Agente de métricas del clúster k8s-infra de SigNoz

Inicio Rápido

1. Instale las Herramientas Requeridas

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 y 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 instalación

terraform --version
terragrunt --version
kubectl version --client
helm version
aws sts get-caller-identity

2. Cree un Nuevo Entorno

Los nuevos entornos se crean copiando env-template-folder y completando los placeholders. Consulte la Guía de Despliegue con Terragrunt para el proceso completo paso a paso. El flujo de alto nivel es:

# 1. Copiar la plantilla
cp -r terragrunt/environments/env-template-folder terragrunt/environments/your-env-name
 
# 2. Completar todos los placeholders <YOUR_*> en:
#    - terragrunt/environments/your-env-name/terragrunt.hcl
#    - terragrunt/environments/your-env-name/state/terragrunt.hcl
#    - terragrunt/environments/your-env-name/values/*.yaml
 
# 3. Inicializar el bucket de estado
cd terragrunt/environments/your-env-name/state
terragrunt apply
 
# 4. Establecer variables de entorno y desplegar
cd ../
export ENABLE_ALB_CONTROLLER=true
export WEB_DOMAIN="app.example.com"
export WEB_CERTIFICATE_ARN="arn:aws:acm:<region>:<account>:certificate/<id>"
# ... (consulte TERRAGRUNT_DEPLOYMENT_GUIDE.md para la lista completa de variables)
 
terragrunt apply

Banderas de Habilitación/Deshabilitación de Servicios

Todos los servicios opcionales se activan a través de variables de entorno. Establézcalas antes de ejecutar terragrunt apply.

Variable	Valor predeterminado	Servicio
`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 HA de PostgreSQL (requiere `ENABLE_CNPG=true`)
`ENABLE_SUPABASE`	`false`	Stack completo de Supabase (requiere `ENABLE_HA_SUPABASE_DB=true`)
`ENABLE_SIGNOZ`	`false`	Observabilidad SigNoz + agente k8s-infra

Orden de Despliegue de Supabase AutoalojadoLos componentes de Supabase deben desplegarse en secuencia:

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

Referencia de Charts Helm

Chart (en `helm-deployment/`)	Namespace	Habilitado por	Descripción
`infrastructure`	`infrastructure`	Siempre	AWS Load Balancer Controller
`odin-services/odin-services`	`default`	Siempre	Web, FastAPI, Celery, Automator, Ingress
`aws-ebs-csi-driver` (upstream)	`kube-system`	Siempre	Driver de volúmenes persistentes EBS
`keda` (upstream)	`keda`	Siempre	Autoescalado de pods
`cloudnative-pg`	`cnpg-system`	`ENABLE_CNPG`	Operador PostgreSQL
`ha-supabase-db`	`ha-supabase-db`	`ENABLE_HA_SUPABASE_DB`	HA Postgres + PgBouncer + respaldos barman
`supabase-kubernetes-ha`	`supabase`	`ENABLE_SUPABASE`	Kong, Auth, Storage, Studio, Realtime
`signoz`	`monitoring`	`ENABLE_SIGNOZ`	Traza distribuida, métricas, logs
`k8s-infra` (upstream)	`monitoring`	`ENABLE_SIGNOZ`	Agente DaemonSet de métricas del clúster

Referencia de Módulos

`modules/eks`

El módulo principal. Provisiona:

VPC con subredes públicas/privadas en 3 AZs
Cluster EKS (Kubernetes 1.33) y grupo de nodos administrado para Karpenter
Controlador Karpenter + NodePool + EC2NodeClass
Roles IAM (cluster, grupo de nodos, Karpenter, controlador ALB, controlador EBS CSI)
Todos los releases de Helm a través del mapa de entrada helm_releases

`modules/aws-services`

Provisiona ElastiCache Redis y Amazon MQ RabbitMQ. Solo activo cuando ENABLE_AWS_SERVICES=true.

`modules/state`

Inicializa el bucket de estado S3 para un nuevo entorno (versionado, cifrado, bloqueo de acceso público).

`modules/helm`

Módulo de release Helm reutilizable que soporta repositorios de charts upstream y charts locales con chart_path.

Configuración del Entorno

Placeholders

Cada valor en env-template-folder que sea específico del entorno usa un placeholder <YOUR_*>. Ejecute lo siguiente para verificar que no quede nada pendiente antes de desplegar:

grep -r "<YOUR_" terragrunt/environments/your-env-name/

Estado Remoto

El estado se almacena en S3 por entorno. El bucket es inicializado por state/terragrunt.hcl y referenciado por root.hcl. El patrón de nombres es ekb-terraform-state-<env-name>.

Secretos

Los valores sensibles (contraseñas, claves API, ARNs de certificados) nunca se comprometen en el repositorio. Se pasan como variables de entorno consumidas por las llamadas get_env() en terragrunt.hcl, o como placeholders <YOUR_*> en archivos de valores que deben completarse antes del despliegue.

Solución de Problemas

Verificar credenciales de AWS

aws sts get-caller-identity

Verificar acceso al cluster

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

Verificar el Controlador ALB

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

Verificar Karpenter

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

Verificar bloqueo de estado

# Desbloquear forzadamente un estado atascado (usar el ID del bloqueo del mensaje de error)
cd terragrunt/environments/your-env-name
terragrunt force-unlock <lock-id>

Verificar que no queden placeholders

grep -r "<YOUR_" terragrunt/environments/your-env-name/

Verificar el estado de los releases Helm

helm list -A
helm status <release-name> -n <namespace>
helm get values <release-name> -n <namespace>

Soporte Multi-Nube (Planificado)

Plataforma	Estado	Módulo
AWS EKS	Activo	`modules/eks`
Azure AKS	Módulo	`modules/aks`
Google GKE	Módulo	`modules/gke`
Bare metal	Módulo	`modules/baremetal`

Get Started!

Offerings

Chat

Agents

Knowledge Base

Workflows

Interfaces

Public Chatbot

Project Settings

My Account

Platform Admin

SDK

General Information

Documentación

Estructura del Repositorio

Inicio Rápido

1. Instale las Herramientas Requeridas

2. Cree un Nuevo Entorno

Banderas de Habilitación/Deshabilitación de Servicios

Referencia de Charts Helm

Referencia de Módulos

`modules/eks`

`modules/aws-services`

`modules/state`

`modules/helm`

Configuración del Entorno

Placeholders

Estado Remoto

Secretos

Solución de Problemas

Soporte Multi-Nube (Planificado)

​Documentación

​Estructura del Repositorio

​Inicio Rápido

​1. Instale las Herramientas Requeridas

​2. Cree un Nuevo Entorno

​Banderas de Habilitación/Deshabilitación de Servicios

​Referencia de Charts Helm

​Referencia de Módulos

​modules/eks

​modules/aws-services

​modules/state

​modules/helm

​Configuración del Entorno

​Placeholders

​Estado Remoto

​Secretos

​Solución de Problemas

​Soporte Multi-Nube (Planificado)

Documentación

Estructura del Repositorio

Inicio Rápido

1. Instale las Herramientas Requeridas

2. Cree un Nuevo Entorno

Banderas de Habilitación/Deshabilitación de Servicios

Referencia de Charts Helm

Referencia de Módulos

`modules/eks`

`modules/aws-services`

`modules/state`

`modules/helm`

Configuración del Entorno

Placeholders

Estado Remoto

Secretos

Solución de Problemas

Soporte Multi-Nube (Planificado)