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

Información

Orden de Despliegue de Supabase Autoalojado

Los 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

aviso

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`

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