iac-duplicate/QUICKSTART.md

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