> ## 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.

# Infraestructura Terraform de EKB

> Terraform and Terragrunt IaC for managing the EKB platform on AWS EKS, with support stubs for GKE, AKS, and bare-metal Kubernetes.

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](/offerings/on-premise/kubernetes-deployment/terragrunt-deployment)           | Guía paso a paso para crear y desplegar un nuevo entorno                                |
| [Descripción General de la Arquitectura AWS](/offerings/on-premise/kubernetes-deployment/aws-architecture)       | Descripción general de la arquitectura, componentes y flujo de datos                    |
| [Estrategia de Recuperación ante Desastres](/offerings/on-premise/kubernetes-deployment/disaster-recovery-guide) | Estrategia DR, objetivos RTO/RPO, sistemas de respaldo y procedimientos de recuperación |
| [Lista de Prerrequisitos](/offerings/on-premise/kubernetes-deployment/eks-deployment-prerequisites)              | 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**

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

```bash theme={null}
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](/offerings/on-premise/kubernetes-deployment/terragrunt-deployment) para el proceso completo paso a paso. El flujo de alto nivel es:

```bash theme={null}
# 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                           |

<Info>
  **Orden de Despliegue de Supabase Autoalojado**

  Los componentes de Supabase deben desplegarse en secuencia:

  ```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>

***

## 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:

```bash theme={null}
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

<Warning>
  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.
</Warning>

***

## Solución de Problemas

**Verificar credenciales de AWS**

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

**Verificar acceso al cluster**

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

**Verificar el Controlador ALB**

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

**Verificar Karpenter**

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

**Verificar bloqueo de estado**

```bash theme={null}
# 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**

```bash theme={null}
grep -r "<YOUR_" terragrunt/environments/your-env-name/
```

**Verificar el estado de los releases Helm**

```bash theme={null}
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` |