iac-duplicate/AGENTS.md

AGENTS.md — iac-duplicate

Toolkit de duplicación de infraestructura para crear entornos de prueba que replican producción SACC v4.

Overview

iac-duplicate es un toolkit de Infrastructure as Code (IaC) diseñado para replicar el entorno de producción SACC v4 en una cuenta AWS de pruebas separada. Contiene Terraform standalone, playbooks de Ansible, una variante de pipeline de Bitbucket, y scripts de automatización.

Propósito: Permitir la creación de entornos de test/QA idénticos a producción para pruebas, desarrollo y validación, sin riesgo de afectar el entorno productivo.

Stack Tecnológico:

• Cloud: AWS (EC2, RDS MariaDB, S3, CloudFront, Route53, ACM, IAM, Lambda, VPC)
• IaC: Terraform (modular, workspaces test/prod, backend S3)
• Configuración: Ansible (post-deploy de servidores)
• CI/CD: Bitbucket Pipelines (variante multi-entorno)
• Frontend: React (S3 + CloudFront)
• Backend: Java/Spring Boot (EC2 como JARs ejecutables)
• Web Server: Nginx (reverse proxy)
• Base de Datos: RDS MariaDB 10.11
• Scheduling: Lambda + EventBridge (apagado automático para ahorro de costos)

Cuenta AWS Test: 668889063715 (mx-central-1)
Cuenta AWS Prod: 523761210517 (mx-central-1)
Dominio Test: dev-sacc.ccsoft.mx
Dominio Prod: sacc.ccsoft.mx
VPC CIDR Test: 10.3.0.0/16
VPC CIDR Prod: 10.2.0.0/16

---

Inventario

Estructura del Proyecto

iac-duplicate/
├── README.md                          # Instrucciones de duplicación y advertencias
├── QUICKSTART.md                      # Guía de inicio rápido (919 líneas, 6 secciones)
├── terraform/                         # Infraestructura como código
│   ├── bootstrap.tf                   # Creación de backend S3/DynamoDB
│   ├── main.tf                        # Orquestación principal de infraestructura
│   ├── variables.tf                   # Variables configurables (32+ variables)
│   ├── terraform.tfvars.example       # Ejemplo de configuración (355 líneas)
│   ├── backend.tf                     # Configuración de backend S3
│   ├── provider.tf                    # Provider AWS
│   ├── outputs.tf                     # Outputs de Terraform
│   ├── environments/                  # Variables por entorno
│   │   ├── test/terraform.tfvars      # Configuración TEST
│   │   └── prod/terraform.tfvars      # Configuración PROD (no usar aquí)
│   ├── modules/                       # Módulos reutilizables
│   │   ├── vpc/                       # VPC, subnets, IGW, route tables
│   │   ├── ec2/                       # Instancia EC2, EIP, key pairs
│   │   ├── rds/                       # Base de datos MariaDB
│   │   ├── security-groups/           # Security groups para EC2 y RDS
│   │   ├── iam/                       # Roles y policies IAM
│   │   ├── s3-cloudfront/             # Bucket S3 + distribución CloudFront
│   │   ├── route53/                   # Registros DNS
│   │   └── lambda-scheduler/          # Funciones Lambda para start/stop
│   └── scripts/
│       └── ec2-user-data.sh           # Script de inicialización de EC2
├── ansible/                           # Configuración post-deploy
│   ├── playbooks/
│   │   └── site.yml                   # Playbook principal (usuarios, nginx, systemd)
│   └── templates/
│       ├── systemd-service.j2         # Template de servicios systemd
│       ├── nginx-sacc4.conf.j2        # Configuración Nginx
│       ├── sacc4.env.j2               # Variables de entorno de aplicación
│       └── logrotate-sacc4.j2         # Configuración de rotación de logs
├── bitbucket/                         # Pipeline CI/CD
│   ├── bitbucket-pipelines.yml        # Pipeline multi-entorno (test/prod)
│   └── README_PIPELINE.md             # Documentación del pipeline
├── scripts/                           # Scripts de automatización
│   ├── create-test-environment.sh     # Crear entorno TEST completo
│   ├── destroy-test-environment.sh    # Destruir entorno TEST de forma segura
│   └── validate-environment.sh        # Validar funcionamiento del entorno
└── docs/                              # Documentación
    └── ANALISIS_CUENTA_668889063715.md # Análisis detallado de cuenta AWS test

Pipeline CI/CD Multi-Entorno

El pipeline de Bitbucket soporta despliegue a TEST (automático) y PROD (manual con aprobación):

Rama	Entorno	Trigger	Cuenta AWS
test / develop	TEST	Automático	668889063715
main / master	PROD	Manual (aprobar en Bitbucket)	523761210517
Pull Requests	Validación	Automático	N/A (solo plan)

Pasos del Pipeline (TEST):

1. Setup Tools - Instala Terraform, Ansible, AWS CLI
2. Validate Terraform - Valida sintaxis y formato
3. Plan Terraform (TEST) - Genera plan de cambios
4. Apply Terraform (TEST) - Aplica infraestructura
5. Deploy Application (TEST) - Configura servidor con Ansible
6. Health Check (TEST) - Verifica puertos 8080-8085
7. Notify - Notificación Telegram (opcional)

Arquitectura AWS (Entorno Test)

                                 +------------------+
                                 |     Usuario      |
                                 +--------+---------+
                                          |
                                          v
+------------------+           +----------+-----------+
|   Route53        |<----------|    CloudFront CDN    |
| (dev-sacc... )   |           |  (SSL via ACM)       |
+------------------+           +----------+-----------+
                                          |
                    +---------------------+---------------------+
                    |                                           |
                    v                                           v
           +----------------+                         +------------------+
           |  S3 Bucket     |                         |  EC2 Instance    |
           | (Frontend      |                         | (Backend API     |
           |  React)        |                         |  Spring Boot)    |
           +----------------+                         +--------+---------+
                                                               |
                                                               v
                                                      +------------------+
                                                      |   Nginx (reverse |
                                                      |    proxy)        |
                                                      +--------+---------+
                                                               |
                                                               v
                                                      +------------------+
                                                      |  RDS MariaDB     |
                                                      |  (Base de datos) |
                                                      +------------------+
                                                               ^
                                                               |
                                                      +------------------+
                                                      |  Lambda Scheduler|
                                                      |  (Start/Stop)    |
                                                      +------------------+

Componentes AWS

Componente	Descripción	Configuración Test
VPC	Red aislada con subnets públicas/privadas	CIDR 10.3.0.0/16
EC2	Instancia Ubuntu 22.04 para JARs Spring Boot	t3.small, 8GB gp2
RDS	MariaDB 10.11 para datos de SACC	db.t3.micro, 20GB
S3	Hosting estático del frontend React	Privado, OAC
CloudFront	CDN para distribución global del frontend	PriceClass_100
Route53	DNS para dev-sacc.ccsoft.mx	Registros A
ACM	Certificados SSL (us-east-1 obligatorio)	Validación DNS
Lambda	Funciones de scheduling (start/stop)	EventBridge cron
IAM	Roles para EC2, Lambda, CI/CD	Least privilege

Microservicios (Puertos 8080-8085)

Puerto	Servicio	Descripción
8080	api-sacc4-authentication	Autenticación y JWT
8081	api-sacc4-users	Gestión de usuarios
8082	api-sacc4-tickets	Tickets y soporte
8083	api-sacc4-privileges	Permisos y privilegios
8084	api-sacc4-rols	Roles del sistema
8085	api-sacc4-associates	Asociados y clientes

---

Acceso Rápido

Requisitos Previos

Herramienta	Versión Mínima	Verificar
AWS CLI	2.x	aws --version
Terraform	>= 1.5.0	terraform -version
Git	Cualquiera	git --version
OpenSSH	Cualquiera	ssh -V
Ansible	2.x+	ansible-playbook --version

Configuración de Credenciales

# Configurar credenciales AWS (cuenta TEST)
aws configure --profile test
# 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 cuenta correcta
aws sts get-caller-identity --profile test
# Debe mostrar: Account = 668889063715

Crear Entorno TEST Completo

cd iac-duplicate/scripts
./create-test-environment.sh

El script realiza:

1. Validación de prerequisitos (AWS CLI, Terraform, credenciales)
2. Verificación de conflictos de nombres
3. Creación de backend S3/DynamoDB
4. terraform init / plan / apply
5. Generación de inventario Ansible
6. Ejecución de playbooks Ansible
7. Verificación de health checks

Destruir Entorno TEST

cd iac-duplicate/scripts
./destroy-test-environment.sh

Opciones:

• --force - Omitir confirmaciones (USAR CON PRECAUCIÓN)
• --skip-rds-backup - Omitir backup de RDS
• --delete-s3 - Eliminar contenido de S3 antes de destruir
• --keep-state - Conservar bucket de estado Terraform

Validar Entorno

cd iac-duplicate/scripts
./validate-environment.sh --full

Validaciones:

• --ssh-only - Solo conectividad SSH
• --services - Solo servicios systemd
• --api - Solo APIs en puertos 8080-8085
• --nginx - Solo Nginx
• --rds - Solo base de datos
• --s3 - Solo bucket S3

Comandos Terraform Manuales

cd iac-duplicate/terraform/environments/test

# Crear backend
terraform init
terraform apply -target=aws_s3_bucket.terraform_state
terraform apply -target=aws_dynamodb_table.terraform_locks

# Configurar variables
cp ../../terraform.tfvars.example terraform.tfvars
# Editar terraform.tfvars con valores correctos

# Desplegar infraestructura
terraform init
terraform plan -var-file=terraform.tfvars
terraform apply -var-file=terraform.tfvars

# Destruir infraestructura
terraform destroy -var-file=terraform.tfvars

Configurar Servidor con Ansible

cd iac-duplicate/ansible
ansible-playbook -i inventory playbooks/site.yml

---

Health Checks

Verificar Infraestructura AWS

# EC2
aws ec2 describe-instances \
    --region mx-central-1 --profile test \
    --query 'Reservations[*].Instances[*].[InstanceId,State.Name,PublicIpAddress]'

# RDS
aws rds describe-db-instances \
    --region mx-central-1 --profile test \
    --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceStatus,Endpoint.Address]'

# S3
aws s3 ls s3://sacc4-frontend-test-668889063715/ --profile test

# CloudFront
aws cloudfront list-distributions --profile test \
    --query 'DistributionList.Items[*].[Id,Status,DomainName]'

Verificar Conectividad y Servicios

# Obtener IP de EC2
EC2_IP=$(terraform output -raw ec2_public_ip)

# SSH
ssh -i ~/.ssh/sacc4-test-key.pem ubuntu@$EC2_IP "echo 'Conexion SSH OK'"

# Nginx
ssh -i ~/.ssh/sacc4-test-key.pem ubuntu@$EC2_IP "sudo systemctl status nginx"

# 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 vía 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"

Verificar Base de Datos

# Obtener endpoint RDS
RDS_ENDPOINT=$(terraform output -raw rds_endpoint)

# Conexión 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 públicamente accesible
aws rds describe-db-instances --region mx-central-1 --profile test \
    --query 'DBInstances[*].PubliclyAccessible'
# Salida esperada: [false]

---

Validación Terraform

# Validar sintaxis
terraform validate

# Formato
terraform fmt -check -recursive

# Plan de cambios (dry-run)
terraform plan -var-file="environments/test/terraform.tfvars"

# Plan de destrucción
terraform plan -destroy -var-file="environments/test/terraform.tfvars"

---

Variables Críticas (terraform.tfvars)

Variable	Descripción	Ejemplo
environment	Entorno de despliegue	test
aws_region	Región AWS	mx-central-1
domain_name	Dominio principal	dev-sacc.ccsoft.mx
api_subdomain	Subdominio API	api.dev-sacc.ccsoft.mx
vpc_cidr	CIDR de la VPC	10.3.0.0/16
ssh_allowed_cidrs	IPs permitidas para SSH	["186.96.145.105/32"]
thoth_public_key	Llave pública de thoth	ssh-ed25519 AAAA...
osiris_public_key	Llave pública de osiris	ssh-ed25519 AAAA...
rds_master_password	Contraseña RDS (16+ chars)	Sacc4_Test_2024!Secure
frontend_bucket_name	Bucket S3 (único global)	sacc4-frontend-test-668889063715
certificate_arn	ARN del certificado ACM	arn:aws:acm:us-east-1:...
enable_scheduling	Apagado automático (ahorro)	true

---

Estimación de Costos (Mensual TEST)

Con Scheduling Habilitado (Recomendado)

Servicio	Tipo	Horas/Día	Costo/Mes (USD)
EC2	t3.small	~10	~$7
RDS	db.t3.micro	~10	~$4
S3	~1GB	24/7	~$0.20
CloudFront	Bajo tráfico	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	Costo/Mes (USD)
EC2 t3.small	~$15
RDS db.t3.micro	~$13
S3	~$0.20
CloudFront	~$0.50
Route53	~$0.50
Lambda	~$0
Data Transfer	~$5
TOTAL	~$35-40/mes

---

Jerarquía de AGENTS

Ruta	Uso
/home/evert/Servidores/Nuve/AWS/proyectosacc/AGENTS.md	Contexto superior (infraestructura principal SACC)
/home/evert/Servidores/Nuve/AWS/proyectosacc/iac-duplicate/AGENTS.md	Este documento (toolkit de duplicación)

---

Reglas de Seguridad

⚠️ ADVERTENCIA CRÍTICA

SOLO para entornos de test. NUNCA ejecutar en producción.
La cuenta 523761210517 tiene producción activa. Este toolkit está diseñado exclusivamente para la cuenta de test 668889063715.

Manejo de Secrets

• NUNCA commitear terraform.tfvars al repositorio (ya está en .gitignore)
• Usar Bitbucket Repository Variables para CI/CD (marcar como Secured)
• Variables locales en archivos .env o terraform.tfvars
• Rotar credenciales periódicamente
• Las contraseñas RDS deben tener mínimo 16 caracteres

AWS IAM

• Usar roles IAM con privilegios mínimos (principle of least privilege)
• Credenciales temporales (session tokens) requieren renovación
• Verificar identidad antes de cada operación: aws sts get-caller-identity

Red

• Restringir Security Groups - No usar 0.0.0.0/0 para SSH
• Configurar ssh_allowed_cidrs con tu IP actual (curl https://checkip.amazonaws.com)
• VPC aislada con subnets públicas y privadas
• RDS en subnets privadas (no accesible públicamente)
• NAT Gateway para salida a Internet desde subnets privadas

SSL/TLS

• Certificados gestionados por AWS ACM
• Para CloudFront, el certificado DEBE estar en us-east-1 (N. Virginia)
• Forzar HTTPS en CloudFront

SSH

• Usuarios autorizados: osiris (ejecuta servicios, UID 997) y thoth (despliegues, UID 1001)
• Grupo: duat (GID 1006)
• Usar llaves ed25519: ssh-keygen -t ed25519 -f ~/.ssh/sacc4-thoth -C "thoth@ccsoft"
• Deshabilitar autenticación por contraseña: PasswordAuthentication no

Auditoría

• Habilitar CloudTrail para auditoría de API calls
• Configurar AWS Config para compliance
• Monitorear costos con AWS Budget (alerta a $50/mes)

CIDR y Conflictos

• TEST usa 10.3.0.0/16 para evitar conflicto con PROD 10.2.0.0/16
• Verificar VPCs existentes antes de crear: aws ec2 describe-vpcs
• Nombres de bucket S3 deben ser únicos globalmente (incluir ID de cuenta)

Backup y Recuperación

• Backup automático RDS: 7 días (configurable)
• El script destroy-test-environment.sh crea snapshot final antes de destruir
• Bucket S3 de estado Terraform tiene versionamiento habilitado

---

Troubleshooting

Problema: Certificado ACM No Se Valida

# 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: Security Group Bloquea SSH

# Obtener IP actual y actualizar
curl -s https://checkip.amazonaws.com
# Editar terraform.tfvars con nueva IP
terraform apply -var-file="terraform.tfvars" -target=module.security_groups

Problema: Terraform State Lock

# Verificar lock activo
aws dynamodb get-item \
    --table-name sacc4-terraform-locks-test-668889063715 \
    --key '{"LockID":{"S":"sacc4-test/infrastructure/terraform.tfstate-md5"}}'

# Forzar unlock (solo si no hay proceso activo)
terraform force-unlock <LOCK_ID>

Problema: Bucket S3 Ya Existe

Los nombres de bucket S3 son únicos globalmente en AWS. Cambiar el nombre en terraform.tfvars:

frontend_bucket_name = "sacc4-frontend-test-668889063715-$(date +%s)"

Problema: RDS No Responde Desde EC2

# Verificar que RDS está en estado "available"
aws rds describe-db-instances --region mx-central-1 --profile test \
    --query 'DBInstances[*].DBInstanceStatus'

# Verificar Security Group de RDS permite tráfico desde SG de EC2
aws ec2 describe-security-groups --region mx-central-1 --profile test \
    --query 'SecurityGroups[*].[GroupName,IpPermissions]'

---

Cómputo Contable Soft SA de CV — Nuve/AWS/proyectosacc/iac-duplicate — Junio 2026