Add complete SACC v4 infrastructure project

- Terraform modules: VPC, EC2, RDS, S3, CloudFront, Route53, Lambda, IAM, Security Groups - Ansible playbooks for server configuration - Scripts: create-test-environment.sh, destroy-test-environment.sh, validate-environment.sh - Documentation: README, QUICKSTART, AGENTS - Jenkins pipeline for automated deployment - Jenkins pipeline for environment destruction
2026-06-03 04:39:01 +00:00
commit 71be2abd2e
27 changed files with 6424 additions and 0 deletions
@@ -0,0 +1,919 @@
+# Guia de Inicio Rapido - Entorno TEST SACC v4
+# ================================================================
+# Cuenta AWS TEST: 668889063715
+# Region: mx-central-1
+# Dominio: dev-sacc.ccsoft.mx
+# Ultima actualizacion: 2026-06-02
+#
+# ATENCION: Este documento contiene comandos MANUALES para ejecutar
+# en AWS Console y Bitbucket. NO ejecutar scripts automaticamente
+# sin revisar los valores.
+# ================================================================
+
+---
+
+## Tabla de Contenidos
+
+1. [Prerrequisitos](#1-prerrequisitos)
+2. [Configuracion Paso a Paso](#2-configuracion-paso-a-paso)
+3. [Comandos de Verificacion](#3-comandos-de-verificacion)
+4. [Estimacion de Costos](#4-estimacion-de-costos)
+5. [Solucion de Problemas](#5-solucion-de-problemas)
+6. [Limpieza (Destruir Entorno)](#6-limpieza-destruir-entorno)
+
+---
+
+## 1. Prerrequisitos
+
+Antes de comenzar, asegurate de tener:
+
+### Herramientas Instaladas
+
+| Herramienta | Version Minima | Comando para verificar |
+|-------------|----------------|------------------------|
+| AWS CLI | 2.x | `aws --version` |
+| Terraform | >= 1.5.0 | `terraform -version` |
+| Git | Cualquiera | `git --version` |
+| OpenSSH | Cualquiera | `ssh -V` |
+
+### Accesos Requeridos
+
+- [ ] Acceso a AWS Console para la cuenta **668889063715** (TEST) con permisos de administrador
+- [ ] Acceso de solo lectura a AWS Console para la cuenta **523761210517** (PROD) - para referencia
+- [ ] Acceso de administrador al repositorio Bitbucket `proyectosacc`
+- [ ] Llave SSH descargada (una de las existentes: `ccsoft-dev-key` o `Sacc-dev`)
+
+### Recursos Ya Existentes en Cuenta TEST
+
+Estos recursos ya estan configurados en la cuenta 668889063715:
+
+- [x] **Route53 Hosted Zone** para `dev-sacc.ccsoft.mx`
+- [x] **IAM Role** `BitbucketProyectosaccCICDRoleDev` para CI/CD
+- [x] **IAM Role** `proyectosacc-ec2-role-dev` para instancias EC2
+- [x] **Key Pairs** `ccsoft-dev-key` y `Sacc-dev`
+
+---
+
+## 2. Configuracion Paso a Paso
+
+### Paso 1: Obtener Tu IP Publica
+
+Necesitas tu IP publica para restringir el acceso SSH en los Security Groups.
+
+```bash
+# Ejecutar en tu terminal
+curl -s https://checkip.amazonaws.com
+```
+
+**Salida esperada:**
+```
+186.96.145.105
+```
+
+💡 **Tip:** Anota esta IP. La usaras en el formato `186.96.145.105/32`.
+
+⚠️ **Advertencia:** Si tu IP cambia (IP dinamica), deberas actualizar los Security Groups.
+
+---
+
+### Paso 2: Crear/Validar Certificado SSL en ACM
+
+CloudFront requiere un certificado SSL. El certificado **DEBE** estar en la region `us-east-1` (N. Virginia), aunque los recursos esten en `mx-central-1`.
+
+#### 2.1 Solicitar Certificado
+
+1. Ir a **AWS Console** -> **Certificate Manager (ACM)**
+2. Cambiar la region a **US East (N. Virginia)** usando el selector de region arriba a la derecha
+3. Clic en **"Request a certificate"**
+4. Seleccionar **"Request a public certificate"**
+5. Clic en **"Next"**
+
+#### 2.2 Configurar Dominio
+
+- **Fully qualified domain name:** `dev-sacc.ccsoft.mx`
+- **Validation method:** DNS validation (recomendado)
+- Clic en **"Request"**
+
+#### 2.3 Validar por DNS
+
+1. En la lista de certificados, encontraras uno con estado **"Pending validation"**
+2. Clic en el **Certificate ID**
+3. En la seccion **"Domains"**, clic en **"Create records in Route 53"**
+4. Seleccionar el dominio `dev-sacc.ccsoft.mx`
+5. Clic en **"Create records"**
+
+#### 2.4 Esperar Validacion
+
+- El estado cambiara a **"Issued"** (generalmente toma 5-15 minutos)
+- Refrescar la pagina cada 2 minutos
+
+#### 2.5 Copiar el ARN
+
+Una vez emitido, copiar el ARN completo:
+
+```
+arn:aws:acm:us-east-1:668889063715:certificate/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
+```
+
+💡 **Tip:** Guarda este ARN en un archivo de texto temporal. Lo necesitaras en el Paso 3.
+
+⚠️ **Advertencia:** Si no completas la validacion DNS, Terraform fallara al crear CloudFront.
+
+---
+
+### Paso 3: Completar terraform.tfvars
+
+El archivo de variables esta ubicado en:
+```
+iac-duplicate/terraform/environments/test/terraform.tfvars
+```
+
+#### 3.1 Variables Requeridas (DEBEN ser modificadas)
+
+Edita el archivo y completa estos valores:
+
+```hcl
+# =============================================================================
+# VARIABLES OBLIGATORIAS - MODIFICAR ANTES DE APLICAR
+# =============================================================================
+
+# Tu IP publica para acceso SSH (obtenida en Paso 1)
+# Formato: ["xxx.xxx.xxx.xxx/32"]
+# Ejemplo: ["186.96.145.105/32"]
+ssh_allowed_cidrs = ["TU_IP_AQUI/32"]
+
+# Contrasena maestra de RDS
+# REQUISITOS: Minimo 16 caracteres, incluir mayusculas, minusculas, numeros y simbolos
+# NO usar: @, /, \"
+# Ejemplo: "Sacc4_Test_2024!Secure"
+rds_master_password = "TU_PASSWORD_SEGURO_AQUI"
+
+# Llave publica SSH para usuario "thoth"
+# Generar con: ssh-keygen -t ed25519 -f ~/.ssh/sacc4-thoth -C "thoth@ccsoft"
+# Copiar el contenido del archivo ~/.ssh/sacc4-thoth.pub
+thoth_public_key = "ssh-ed25519 AAAA... thoth@ccsoft"
+
+# Llave publica SSH para usuario "osiris"
+# Generar con: ssh-keygen -t ed25519 -f ~/.ssh/sacc4-osiris -C "osiris@ccsoft"
+# Copiar el contenido del archivo ~/.ssh/sacc4-osiris.pub
+osiris_public_key = "ssh-ed25519 AAAA... osiris@ccsoft"
+
+# ARN del certificado SSL (obtenido en Paso 2)
+# Dejar vacio "" si aun no tienes certificado
+# Ejemplo: "arn:aws:acm:us-east-1:668889063715:certificate/..."
+certificate_arn = ""
+```
+
+#### 3.2 Variables Recomendadas (revisar valores)
+
+```hcl
+# Nombre del bucket S3 para frontend
+# DEBE ser unico a nivel global en AWS
+frontend_bucket_name = "sacc4-frontend-test-668889063715"
+
+# Tipo de instancia EC2
+ec2_instance_type = "t3.small"
+
+# Clase de instancia RDS
+rds_instance_class = "db.t3.micro"
+
+# Region y entorno (generalmente no cambian)
+aws_region  = "mx-central-1"
+environment = "test"
+project_name = "sacc4"
+```
+
+#### 3.3 Ejemplo Completo de terraform.tfvars
+
+```hcl
+# =============================================================================
+# VARIABLES DE ENTORNO TEST - SACC v4
+# Cuenta AWS: 668889063715
+# =============================================================================
+
+aws_region   = "mx-central-1"
+environment  = "test"
+project_name = "sacc4"
+
+# Dominio principal para el entorno de test
+domain_name   = "dev-sacc.ccsoft.mx"
+api_subdomain = "api.dev-sacc.ccsoft.mx"
+
+# Networking
+vpc_cidr             = "10.3.0.0/16"
+availability_zones   = ["mx-central-1a", "mx-central-1b"]
+public_subnet_cidrs  = ["10.3.1.0/24", "10.3.2.0/24"]
+private_subnet_cidrs = ["10.3.10.0/24", "10.3.11.0/24"]
+
+# EC2
+ec2_instance_type         = "t3.small"
+ec2_ami                   = "ami-0f553e2869648134e"
+ec2_root_volume_size      = 8
+ec2_root_volume_type      = "gp2"
+ec2_root_volume_encrypted = true
+
+# SSH - REEMPLAZAR con tu IP publica
+ssh_allowed_cidrs = ["186.96.145.105/32"]
+
+# Llaves SSH - REEMPLAZAR con tus llaves publicas reales
+thoth_public_key  = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAII/RcJmEYOBpfq1tSLltV1pyNB55l1jA2zYr5ZNJ0f41 thoth@ccsoft"
+osiris_public_key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFo6CycfgIuCCSVZbhuPwqlAVDxY8YWb1xpvpqxSzMjR osiris@ccsoft"
+
+# RDS
+rds_instance_class        = "db.t3.micro"
+rds_engine                = "mariadb"
+rds_engine_version        = "10.11.16"
+rds_allocated_storage     = 20
+rds_max_allocated_storage = 100
+rds_db_name               = "ccsoft_sacc4_test"
+rds_master_username       = "sacc_admin_test"
+rds_master_password       = "Sacc4_Test_2024!Secure"
+
+rds_backup_retention_period = 7
+rds_backup_window           = "03:00-04:00"
+rds_maintenance_window      = "Mon:04:00-Mon:05:00"
+
+# Scheduling (apagado automatico para ahorrar costos en test)
+enable_scheduling   = true
+schedule_timezone   = "America/Mexico_City"
+schedule_start_cron = "cron(0 13 ? * MON-FRI *)"
+schedule_stop_cron  = "cron(0 0 ? * TUE-SAT *)"
+
+# Frontend
+frontend_bucket_name = "sacc4-frontend-test-668889063715"
+cloudfront_price_class    = "PriceClass_100"
+enable_cloudfront_logging = false
+
+# Certificado SSL (dejar vacio si aun no esta listo)
+certificate_arn = ""
+
+# Tags
+common_tags = {
+  Project   = "proyectosacc"
+  ManagedBy = "terraform"
+  Team      = "infra"
+  Purpose   = "test-environment"
+}
+```
+
+⚠️ **Advertencia:** NUNCA commitear `terraform.tfvars` al repositorio. El archivo ya esta en `.gitignore`.
+
+💡 **Tip:** Si necesitas regenerar llaves SSH, ejecuta:
+```bash
+ssh-keygen -t ed25519 -f ~/.ssh/sacc4-thoth -C "thoth@ccsoft"
+ssh-keygen -t ed25519 -f ~/.ssh/sacc4-osiris -C "osiris@ccsoft"
+```
+
+---
+
+### Paso 4: Inicializar Backend de Terraform
+
+Terraform necesita un bucket S3 y una tabla DynamoDB para guardar el estado.
+
+#### 4.1 Configurar Credenciales AWS
+
+```bash
+# Usando AWS CLI (recomendado)
+aws configure --profile test
+# Ingresar:
+# AWS Access Key ID: [tu access key de cuenta 668889063715]
+# AWS Secret Access Key: [tu secret key]
+# Default region name: mx-central-1
+# Default output format: json
+
+# Verificar que estas usando la cuenta correcta
+aws sts get-caller-identity --profile test
+```
+
+**Salida esperada:**
+```json
+{
+    "UserId": "AROA...:usuario",
+    "Account": "668889063715",
+    "Arn": "arn:aws:sts::668889063715:assumed-role/..."
+}
+```
+
+⚠️ **Advertencia:** Verifica que el Account sea **668889063715**. Si ves 523761210517, estas en PRODUCCION.
+
+#### 4.2 Crear Backend (Bucket S3 + DynamoDB)
+
+```bash
+cd iac-duplicate/terraform/environments/test
+
+# Crear bucket S3 para estado Terraform
+aws s3api create-bucket \
+    --bucket sacc4-terraform-state-test-668889063715 \
+    --region mx-central-1 \
+    --create-bucket-configuration LocationConstraint=mx-central-1 \
+    --profile test
+
+# Habilitar versionamiento
+aws s3api put-bucket-versioning \
+    --bucket sacc4-terraform-state-test-668889063715 \
+    --versioning-configuration Status=Enabled \
+    --profile test
+
+# Habilitar encriptacion
+aws s3api put-bucket-encryption \
+    --bucket sacc4-terraform-state-test-668889063715 \
+    --server-side-encryption-configuration '{
+        "Rules": [{"ApplyServerSideEncryptionByDefault": {"SSEAlgorithm": "AES256"}}]
+    }' \
+    --profile test
+
+# Crear tabla DynamoDB para locks
+aws dynamodb create-table \
+    --table-name sacc4-terraform-locks-test-668889063715 \
+    --attribute-definitions AttributeName=LockID,AttributeType=S \
+    --key-schema AttributeName=LockID,KeyType=HASH \
+    --billing-mode PAY_PER_REQUEST \
+    --region mx-central-1 \
+    --profile test
+```
+
+💡 **Tip:** Si los recursos ya existen, los comandos anteriores daran error. Esto es normal y puedes continuar.
+
+#### 4.3 Inicializar Terraform
+
+```bash
+terraform init
+```
+
+**Salida esperada:**
+```
+Initializing the backend...
+Successfully configured the backend "s3"!
+
+Initializing provider plugins...
+- Finding hashicorp/aws versions matching "~> 5.0"...
+- Installing hashicorp/aws v5.x.x...
+
+Terraform has been successfully initialized!
+```
+
+---
+
+### Paso 5: Validar y Planificar
+
+#### 5.1 Validar Sintaxis
+
+```bash
+terraform validate
+```
+
+**Salida esperada:**
+```
+Success! The configuration is valid.
+```
+
+#### 5.2 Verificar Plan
+
+```bash
+terraform plan -var-file="terraform.tfvars"
+```
+
+⚠️ **Advertencia:** Revisa CUIDADOSAMENTE la salida. Verifica que:
+- No se vayan a destruir recursos existentes
+- Los nombres de recursos sean correctos
+- La region sea `mx-central-1`
+
+El plan mostrara todos los recursos que se crearan:
+- 1 VPC
+- 2 Subnets publicas
+- 2 Subnets privadas
+- 1 Internet Gateway
+- 1 Instancia EC2
+- 1 Instancia RDS
+- 1 Bucket S3
+- 1 Distribucion CloudFront
+- 2 Funciones Lambda (scheduling)
+- Security Groups, IAM Roles, Route53 records
+
+---
+
+### Paso 6: Aplicar Infraestructura
+
+```bash
+terraform apply -var-file="terraform.tfvars"
+```
+
+1. Terraform pedira confirmacion: escribir **"yes"**
+2. El proceso toma **15-25 minutos**
+3. RDS es el recurso que mas tarda en crear (10-15 minutos)
+
+**Salida esperada al finalizar:**
+```
+Apply complete! Resources: 35 added, 0 changed, 0 destroyed.
+
+Outputs:
+
+ec2_public_ip = "X.X.X.X"
+rds_endpoint = "sacc4-test-db-prod.XXXXXXXX.us-east-1.rds.amazonaws.com"
+frontend_url = "https://dev-sacc.ccsoft.mx"
+```
+
+💡 **Tip:** Guarda los outputs en un archivo para referencia:
+```bash
+terraform output -json > terraform-outputs.json
+```
+
+⚠️ **Advertencia:** Si el comando falla a mitad de ejecucion, ejecuta `terraform apply` nuevamente. Terraform reanudara desde donde se detuvo.
+
+---
+
+### Paso 7: Configurar Variables en Bitbucket
+
+Estas variables permiten que el pipeline CI/CD despliegue automaticamente.
+
+#### 7.1 Navegar a Configuracion
+
+1. Ir a **Bitbucket** -> **Repositorio proyectosacc**
+2. Clic en **"Repository settings"** (engranaje, barra lateral izquierda)
+3. En la seccion **Pipelines**, clic en **"Repository variables"**
+
+#### 7.2 Variables para Entorno TEST
+
+| Variable | Valor | Secured |
+|----------|-------|---------|
+| `TEST_AWS_ACCESS_KEY_ID` | [Access Key de cuenta 668889063715] | Si |
+| `TEST_AWS_SECRET_ACCESS_KEY` | [Secret Key de cuenta 668889063715] | Si |
+| `TEST_AWS_SESSION_TOKEN` | [Session Token si aplica] | Si |
+| `TEST_AWS_ACCOUNT_ID` | `668889063715` | No |
+| `TEST_AWS_REGION` | `mx-central-1` | No |
+| `TEST_AWS_ROLE_ARN` | `arn:aws:iam::668889063715:role/BitbucketProyectosaccCICDRoleDev` | No |
+
+#### 7.3 Variables para Entorno PROD (solo referencia)
+
+| Variable | Valor | Secured |
+|----------|-------|---------|
+| `PROD_AWS_ACCOUNT_ID` | `523761210517` | No |
+| `PROD_AWS_REGION` | `mx-central-1` | No |
+| `PROD_AWS_ROLE_ARN` | `arn:aws:iam::523761210517:role/BitbucketProyectosaccCICDRole` | No |
+
+#### 7.4 Variables de Notificaciones (opcional)
+
+| Variable | Valor | Secured |
+|----------|-------|---------|
+| `TELEGRAM_BOT_TOKEN` | [Token del bot de @BotFather] | Si |
+| `TELEGRAM_CHAT_ID` | [ID del chat de Telegram] | No |
+
+#### 7.5 Variables de Conexion SSH
+
+| Variable | Valor | Secured |
+|----------|-------|---------|
+| `SSH_PRIVATE_KEY` | [Contenido completo de la llave privada .pem] | Si |
+| `SSH_USER` | `ubuntu` | No |
+| `SERVER_HOST` | [IP publica de EC2 despues de crearla] | No |
+
+💡 **Tip:** La IP publica de EC2 la obtienes con:
+```bash
+cd iac-duplicate/terraform/environments/test
+terraform output ec2_public_ip
+```
+
+⚠️ **Advertencia:** Marca como **"Secured"** todas las variables que contengan passwords, tokens o llaves privadas. Bitbucket las ocultara en los logs.
+
+---
+
+### Paso 8: Desplegar Aplicacion
+
+Una vez configuradas las variables de Bitbucket:
+
+```bash
+# En tu repositorio local
+git checkout test
+git add .
+git commit -m "feat: configurar entorno test"
+git push origin test
+```
+
+El pipeline se ejecutara automaticamente:
+1. **Setup Tools** - Instala dependencias
+2. **Validate Terraform** - Valida sintaxis
+3. **Plan Terraform** - Genera plan de cambios
+4. **Apply Terraform** - Aplica infraestructura
+5. **Deploy Application** - Configura servidor con Ansible
+6. **Health Check** - Verifica que todo funciona
+
+💡 **Tip:** Puedes monitorear el pipeline en Bitbucket -> Pipelines.
+
+---
+
+## 3. Comandos de Verificacion
+
+Despues del despliegue, ejecuta estos comandos para verificar que todo funciona:
+
+### 3.1 Verificar Infraestructura AWS
+
+```bash
+# Verificar EC2
+aws ec2 describe-instances \
+    --region mx-central-1 \
+    --profile test \
+    --query 'Reservations[*].Instances[*].[InstanceId,State.Name,PublicIpAddress,InstanceType]'
+
+# Verificar RDS
+aws rds describe-db-instances \
+    --region mx-central-1 \
+    --profile test \
+    --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceStatus,Endpoint.Address]'
+
+# Verificar S3
+aws s3 ls s3://sacc4-frontend-test-668889063715/ --profile test
+
+# Verificar CloudFront
+aws cloudfront list-distributions \
+    --profile test \
+    --query 'DistributionList.Items[*].[Id,Status,DomainName]'
+
+# Verificar Lambda
+aws lambda list-functions \
+    --region mx-central-1 \
+    --profile test \
+    --query 'Functions[*].[FunctionName,State]'
+```
+
+### 3.2 Verificar Conectividad
+
+```bash
+# Obtener IP de EC2
+EC2_IP=$(terraform output -raw ec2_public_ip)
+
+# Verificar SSH
+ssh -i ~/.ssh/sacc4-test-key.pem ubuntu@$EC2_IP "echo 'Conexion SSH OK'"
+
+# Verificar Nginx
+ssh -i ~/.ssh/sacc4-test-key.pem ubuntu@$EC2_IP "sudo systemctl status nginx"
+
+# Verificar servicios Java (puertos 8080-8085)
+for port in 8080 8081 8082 8083 8084 8085; do
+  echo "Puerto $port: $(ssh -i ~/.ssh/sacc4-test-key.pem ubuntu@$EC2_IP "curl -s -o /dev/null -w '%{http_code}' http://localhost:$port/actuator/health" 2>/dev/null || echo 'FAIL')"
+done
+
+# Health check via dominio
+curl -f https://dev-sacc.ccsoft.mx/api/health || echo "API no responde"
+curl -f -I https://dev-sacc.ccsoft.mx || echo "Frontend no responde"
+```
+
+### 3.3 Verificar Base de Datos
+
+```bash
+# Obtener endpoint RDS
+RDS_ENDPOINT=$(terraform output -raw rds_endpoint)
+
+# Verificar conexion desde EC2
+ssh -i ~/.ssh/sacc4-test-key.pem ubuntu@$EC2_IP \
+    "mysql -h $RDS_ENDPOINT -u sacc_app_user -p -e 'SELECT 1;'"
+
+# Verificar que RDS no es publicamente accesible
+aws rds describe-db-instances \
+    --region mx-central-1 \
+    --profile test \
+    --query 'DBInstances[*].PubliclyAccessible'
+# Salida esperada: [false]
+```
+
+### 3.4 Verificar DNS
+
+```bash
+# Verificar que los registros DNS resuelven correctamente
+dig +short dev-sacc.ccsoft.mx
+dig +short api.dev-sacc.ccsoft.mx
+
+# Verificar certificado SSL
+curl -vI https://dev-sacc.ccsoft.mx 2>&1 | grep "SSL certificate"
+```
+
+---
+
+## 4. Estimacion de Costos
+
+### Costo Mensual Aproximado (TEST)
+
+#### Con Scheduling Habilitado (Recomendado)
+
+El scheduling apaga EC2 y RDS automaticamente fuera de horario laboral:
+
+| Servicio | Tipo | Horas/Dia | Costo/Mes (USD) |
+|----------|------|-----------|-----------------|
+| EC2 | t3.small | ~10 | ~$7 |
+| RDS | db.t3.micro | ~10 | ~$4 |
+| S3 | ~1GB | 24/7 | ~$0.20 |
+| CloudFront | Bajo trafico | 24/7 | ~$0.50 |
+| Route53 | 1 hosted zone | 24/7 | ~$0.50 |
+| Lambda | 2 funciones | 24/7 | ~$0 |
+| Data Transfer | Estimado | - | ~$1 |
+| **TOTAL** | | | **~$13/mes** |
+
+#### Sin Scheduling (24/7)
+
+| Servicio | Tipo | Costo/Mes (USD) |
+|----------|------|-----------------|
+| EC2 | t3.small | ~$15 |
+| RDS | db.t3.micro | ~$13 |
+| S3 | ~1GB | ~$0.20 |
+| CloudFront | Bajo trafico | ~$0.50 |
+| Route53 | 1 hosted zone | ~$0.50 |
+| Lambda | 2 funciones | ~$0 |
+| Data Transfer | Estimado | ~$5 |
+| **TOTAL** | | **~$35-40/mes** |
+
+💡 **Tip:** El scheduling ahorra aproximadamente **$20-25/mes** apagando recursos en horario no laboral.
+
+⚠️ **Advertencia:** Los costos pueden variar segun el uso real. Configurar un **AWS Budget** con alerta a $50/mes:
+```bash
+aws budgets create-budget --budget file://budget.json --notifications-with-subscribers file://notifications.json
+```
+
+---
+
+## 5. Solucion de Problemas
+
+### Problema 1: Certificado ACM No Se Valida
+
+**Sintoma:** CloudFront muestra error o Terraform falla con certificado no encontrado.
+
+**Solucion:**
+1. Verificar que el certificado esta en **us-east-1** (N. Virginia)
+2. Verificar que los registros CNAME de validacion existen en Route53
+3. Esperar 15-30 minutos despues de crear el registro DNS
+4. Si persiste, eliminar el certificado y solicitar uno nuevo
+
+```bash
+# Verificar estado del certificado
+aws acm describe-certificate \
+    --certificate-arn arn:aws:acm:us-east-1:668889063715:certificate/XXXX \
+    --region us-east-1 \
+    --query 'Certificate.Status'
+```
+
+---
+
+### Problema 2: Security Group Bloquea SSH
+
+**Sintoma:** `ssh: connect to host X.X.X.X port 22: Connection timed out`
+
+**Solucion:**
+1. Verificar que tu IP actual esta en `ssh_allowed_cidrs`
+2. Si tu IP cambio, actualizar terraform.tfvars y re-aplicar:
+
+```bash
+# Obtener tu IP actual
+curl -s https://checkip.amazonaws.com
+
+# Editar terraform.tfvars con la nueva IP
+terraform apply -var-file="terraform.tfvars" -target=module.security_groups
+```
+
+3. Verificar que el Security Group permite puerto 22 desde tu CIDR
+
+---
+
+### Problema 3: Contrasena RDS Demasiado Corta
+
+**Sintoma:** Terraform falla con `InvalidParameterValue: Password must be at least 16 characters`
+
+**Solucion:**
+```hcl
+# terraform.tfvars - Usar contrasena de 16+ caracteres
+rds_master_password = "Sacc4_Test_2024!Secure"
+```
+
+Requisitos:
+- Minimo 16 caracteres
+- Al menos 1 mayuscula
+- Al menos 1 minuscula
+- Al menos 1 numero
+- Al menos 1 simbolo
+- NO usar: `@`, `/`, `\`, `"`
+
+---
+
+### Problema 4: Terraform State Lock
+
+**Sintoma:** `Error acquiring the state lock: ConditionalCheckFailedException`
+
+**Solucion:**
+```bash
+# Verificar si hay un lock activo
+aws dynamodb get-item \
+    --table-name sacc4-terraform-locks-test-668889063715 \
+    --key '{"LockID":{"S":"sacc4-test/infrastructure/terraform.tfstate-md5"}}' \
+    --region mx-central-1
+
+# Si el proceso anterior se murio, forzar unlock
+terraform force-unlock <LOCK_ID>
+```
+
+⚠️ **Advertencia:** Solo usar `force-unlock` si estas SEGURO de que no hay otro proceso ejecutando Terraform.
+
+---
+
+### Problema 5: Bitbucket Pipeline Falla
+
+**Sintoma:** Pipeline falla en paso "Apply Terraform" o "Deploy Application"
+
+**Solucion:**
+
+1. **Verificar credenciales AWS:**
+```bash
+# En tu local, verificar que las credenciales funcionan
+aws sts get-caller-identity --profile test
+```
+
+2. **Verificar variables en Bitbucket:**
+   - Ir a Repository Settings -> Repository variables
+   - Confirmar que `TEST_AWS_ACCESS_KEY_ID` y `TEST_AWS_SECRET_ACCESS_KEY` estan correctas
+   - Confirmar que estan marcadas como "Secured"
+
+3. **Verificar workspace de Terraform:**
+```bash
+# El pipeline debe seleccionar el workspace test
+terraform workspace select test
+```
+
+4. **Verificar archivo terraform.tfvars:**
+   - Confirmar que existe en `iac-duplicate/terraform/environments/test/terraform.tfvars`
+   - Confirmar que tiene todos los valores requeridos
+
+5. **Verificar IP en Security Group:**
+   - Si el pipeline no puede conectar por SSH, verificar que la IP del runner de Bitbucket esta permitida
+
+---
+
+### Problema 6: Bucket S3 Ya Existe
+
+**Sintoma:** `Error creating S3 bucket: BucketAlreadyExists`
+
+**Solucion:**
+Los nombres de bucket S3 son unicos GLOBALMENTE en AWS. Cambiar el nombre:
+
+```hcl
+# terraform.tfvars
+frontend_bucket_name = "sacc4-frontend-test-668889063715-$(date +%s)"
+```
+
+O usar un nombre diferente:
+```hcl
+frontend_bucket_name = "mi-empresa-sacc4-test-668889063715"
+```
+
+---
+
+### Problema 7: RDS No Responde Desde EC2
+
+**Sintoma:** La aplicacion no puede conectar a la base de datos.
+
+**Solucion:**
+```bash
+# Verificar que RDS esta en estado "available"
+aws rds describe-db-instances \
+    --region mx-central-1 \
+    --profile test \
+    --query 'DBInstances[*].DBInstanceStatus'
+
+# Verificar Security Group de RDS permite trafico desde SG de EC2
+aws ec2 describe-security-groups \
+    --region mx-central-1 \
+    --profile test \
+    --query 'SecurityGroups[*].[GroupName,IpPermissions]'
+
+# Probar conexion desde EC2
+ssh -i ~/.ssh/sacc4-test-key.pem ubuntu@[EC2_IP] \
+    "nc -zv [RDS_ENDPOINT] 3306"
+```
+
+---
+
+## 6. Limpieza (Destruir Entorno)
+
+⚠️ **ATENCION:** Esta accion es IRREVERSIBLE. Se destruiran TODOS los recursos del entorno TEST.
+
+### 6.1 Metodo Seguro (Recomendado)
+
+```bash
+cd iac-duplicate/terraform/environments/test
+
+# Verificar que estas en la cuenta correcta
+aws sts get-caller-identity --profile test
+# Confirmar: Account = 668889063715
+
+# Crear backup de RDS (opcional pero recomendado)
+aws rds create-db-snapshot \
+    --db-instance-identifier sacc4-test-db-prod \
+    --db-snapshot-identifier sacc4-test-final-$(date +%Y%m%d-%H%M%S) \
+    --region mx-central-1 \
+    --profile test
+
+# Destruir infraestructura
+terraform destroy -var-file="terraform.tfvars"
+```
+
+1. Terraform mostrara un plan de destruccion
+2. Escribir **"yes"** para confirmar
+3. El proceso toma **10-15 minutos**
+
+### 6.2 Usar Script de Destruccion
+
+Existe un script automatizado con confirmaciones adicionales:
+
+```bash
+cd iac-duplicate/scripts
+./destroy-test-environment.sh
+```
+
+El script:
+1. Pide confirmacion multiple (escribir "DESTRUIR" y luego "SI")
+2. Crea snapshot final de RDS
+3. Ejecuta `terraform destroy`
+4. Opcionalmente elimina bucket de estado y tabla DynamoDB
+
+### 6.3 Opciones del Script
+
+```bash
+# Omitir confirmaciones (USAR CON PRECAUCION)
+./destroy-test-environment.sh --force
+
+# Omitir backup de RDS
+./destroy-test-environment.sh --skip-rds-backup
+
+# Eliminar contenido de S3 antes de destruir
+./destroy-test-environment.sh --delete-s3
+
+# Conservar bucket de estado Terraform
+./destroy-test-environment.sh --keep-state
+```
+
+### 6.4 Destruir desde Bitbucket
+
+Tambien puedes destruir el entorno desde el pipeline:
+
+1. Ir a **Bitbucket** -> **Pipelines** -> **Run pipeline**
+2. Seleccionar branch **test**
+3. Seleccionar pipeline **destroy-test**
+4. Clic en **"Run"**
+
+⚠️ **Advertencia:** Este pipeline destruira TODO el entorno de test sin pedir confirmacion adicional.
+
+### 6.5 Verificar Destruccion Completa
+
+```bash
+# Verificar que no quedan instancias EC2
+aws ec2 describe-instances --region mx-central-1 --profile test \
+    --filters "Name=instance-state-name,Values=running" \
+    --query 'Reservations[*].Instances[*].InstanceId'
+# Salida esperada: null o lista vacia
+
+# Verificar que no quedan instancias RDS
+aws rds describe-db-instances --region mx-central-1 --profile test \
+    --query 'DBInstances[*].DBInstanceIdentifier'
+# Salida esperada: null o lista vacia
+
+# Verificar que no quedan distribuciones CloudFront activas
+aws cloudfront list-distributions --profile test \
+    --query 'DistributionList.Items[?Status==`Deployed`].Id'
+# Salida esperada: null o lista vacia
+```
+
+---
+
+## Checklist Final
+
+Antes de considerar el entorno como listo, verifica:
+
+- [ ] Las 4 variables obligatorias estan completadas en `terraform.tfvars`
+  - [ ] `ssh_allowed_cidrs` con tu IP actual
+  - [ ] `rds_master_password` con 16+ caracteres seguros
+  - [ ] `thoth_public_key` con tu llave publica
+  - [ ] `osiris_public_key` con tu llave publica
+- [ ] Certificado ACM creado y validado en us-east-1 (o dejado vacio)
+- [ ] Backend S3 y DynamoDB creados
+- [ ] `terraform validate` pasa sin errores
+- [ ] `terraform plan` muestra solo recursos a CREAR (ninguno a destruir)
+- [ ] Variables de Bitbucket configuradas
+- [ ] Pipeline ejecutado exitosamente
+- [ ] Health checks pasan (puertos 8080-8085)
+- [ ] DNS resuelve correctamente (`dev-sacc.ccsoft.mx`)
+- [ ] Conexion a RDS funciona desde EC2
+- [ ] Scheduling configurado (ahorro de costos)
+
+---
+
+## Referencias Rapidas
+
+| Recurso | Valor / Comando |
+|---------|-----------------|
+| Cuenta TEST | `668889063715` |
+| Cuenta PROD | `523761210517` |
+| Region | `mx-central-1` |
+| Dominio TEST | `dev-sacc.ccsoft.mx` |
+| API TEST | `api.dev-sacc.ccsoft.mx` |
+| Pipeline | Rama `test` -> deploy automatico |
+| Destruir | `./scripts/destroy-test-environment.sh` |
+| Logs Terraform | `terraform output -json > outputs.json` |
+
+---
+
+*Documento generado para proyectosacc - SACC v4*
+*NO modificar archivos existentes sin revision*