feat(pipeline): Add SSH key rotation, health checks, and manual approval

Security & Operations Improvements: - Add step 06_update_ssh_keys to rotate authorized_keys on EC2 before each deployment, ensuring only current pipeline can access - Add step 09_health_check with retry logic (12 retries, 10s interval) verifying API backend (/actuator/health), CloudFront, and RDS - Add manual approval (trigger: manual) for production deployment with terraform plan saved as artifact (prod.tfplan) - Document terraform auto-approve policy: dev automatic, prod manual - Use DEV_DB_HOST and PROD_DB_HOST variables for RDS connectivity checks - Reorder steps: 7 steps → 9 steps standard CCsoft pipeline Closes pipeline security gaps and adds post-deploy verification.
2026-04-20 17:47:15 -06:00
parent f32b58fc46
commit defce6933d
4 changed files with 623 additions and 28 deletions
@@ -0,0 +1,399 @@
+# 📋 GUÍA COMPLETA PARA DESARROLLO - CI/CD proyectosacc
+
+> **Fecha:** 17 de Abril 2026
+> **Proyecto:** proyectosacc (SACC)
+> **Repositorio:** https://bitbucket.org/ccsoft1/proyectosacc
+> **Cuenta AWS:** 668889063715 (Desarrollo)
+
+---
+
+## 🎯 RESUMEN EJECUTIVO
+
+Esta guía contiene toda la información necesaria para que el equipo de desarrollo configure y use el pipeline CI/CD del proyecto `proyectosacc`.
+
+**Estado del Pipeline:** ✅ Funcionando
+**Último Build:** #67 (Exitoso)
+**Infraestructura:** ✅ Creada y validada
+
+---
+
+## 📁 ESTRUCTURA DEL PROYECTO
+
+```
+proyectosacc/
+├── bitbucket-pipelines.yml          # Pipeline CI/CD (7 pasos)
+├── scripts/
+│   ├── aws-oidc-setup.sh            # Configuración OIDC AWS
+│   ├── telegram-pipeline-notify.sh  # Notificaciones Telegram
+│   ├── terraform-lock-cleanup.sh    # Limpieza de locks Terraform
+│   ├── deploy.sh                    # Script de deploy manual
+│   ├── health-check.sh              # Health check de servicios
+│   ├── rollback.sh                  # Rollback de deploys
+│   └── deploy-frontend-s3.sh        # Deploy frontend a S3
+├── terraform/
+│   ├── main.tf                      # Infraestructura principal
+│   ├── variables.tf                 # Variables de Terraform
+│   ├── outputs.tf                   # Outputs de Terraform
+│   ├── backend.tf                   # Configuración backend S3
+│   ├── backend.dev.hcl              # Backend desarrollo
+│   ├── backend.prod.hcl             # Backend producción
+│   ├── oidc-bitbucket.tf            # Configuración OIDC
+│   ├── provider.tf                  # Providers AWS
+│   ├── user-data.sh                 # Script inicialización EC2
+│   └── environments/
+│       ├── dev.tfvars               # Variables desarrollo
+│       └── prod.tfvars              # Variables producción
+├── nginx/                           # Configuración nginx
+├── docs/                            # Documentación
+├── .env.dev                         # Variables entorno dev
+├── .env.prod                        # Variables entorno prod
+└── .gitignore
+```
+
+---
+
+## 🔧 CONFIGURACIÓN REQUERIDA EN BITBUCKET
+
+### 1. Variables de Repositorio (Repository Variables)
+
+Ve a: **Bitbucket → Repositorio → Repository settings → Repository variables**
+
+#### Variables para Desarrollo (developer)
+
+| Variable | Descripción | Valor / Ejemplo |
+|----------|-------------|-----------------|
+| `AWS_DEFAULT_REGION` | Región AWS | `mx-central-1` |
+| `DEV_DB_PASSWORD` | Contraseña BD MariaDB | *(solicitar a Infra)* |
+| `DEV_S3_FRONTEND_BUCKET` | Bucket S3 frontend | `ccsoft-proyectosacc-frontend-dev` |
+| `DEV_S3_ARTIFACTS_BUCKET` | Bucket S3 artifacts | `ccsoft-proyectosacc-artifacts-dev` |
+| `DEV_SERVER_IP_PROYECTOSACC` | IP servidor EC2 | `78.12.135.184` |
+| `DEV_SERVER_USER_PROYECTOSACC` | Usuario SSH | `thoth` |
+| `DEV_SSH_PORT_PROYECTOSACC` | Puerto SSH | `22` |
+| `DEV_SSH_PRIVATE_KEY_THOTH_PROYECTOSACC` | Llave SSH (Base64) | *(solicitar a Infra)* |
+| `DEV_TELEGRAM_BOT_TOKEN` | Token bot Telegram | *(solicitar a Infra)* |
+| `DEV_TELEGRAM_CHAT_ID` | ID chat Telegram | *(solicitar a Infra)* |
+
+#### Variables para Producción (master)
+
+| Variable | Descripción | Valor / Ejemplo |
+|----------|-------------|-----------------|
+| `AWS_DEFAULT_REGION` | Región AWS | `mx-central-1` |
+| `PROD_DB_PASSWORD` | Contraseña BD MariaDB | *(solicitar a Infra)* |
+| `PROD_S3_FRONTEND_BUCKET` | Bucket S3 frontend | *(configurar)* |
+| `PROD_S3_ARTIFACTS_BUCKET` | Bucket S3 artifacts | *(configurar)* |
+| `PROD_SERVER_IP_PROYECTOSACC` | IP servidor EC2 | *(configurar)* |
+| `PROD_SERVER_USER_PROYECTOSACC` | Usuario SSH | `thoth` |
+| `PROD_SSH_PORT_PROYECTOSACC` | Puerto SSH | `22` |
+| `PROD_SSH_PRIVATE_KEY_THOTH_PROYECTOSACC` | Llave SSH (Base64) | *(solicitar a Infra)* |
+| `PROD_TELEGRAM_BOT_TOKEN` | Token bot Telegram | *(solicitar a Infra)* |
+| `PROD_TELEGRAM_CHAT_ID` | ID chat Telegram | *(solicitar a Infra)* |
+
+### 2. Configuración OIDC (OpenID Connect)
+
+El pipeline usa OIDC para autenticación con AWS. **No se requieren credenciales estáticas**.
+
+**Configuración ya implementada:**
+- Rol IAM: `BitbucketProyectosaccCICDRoleDev`
+- Proveedor OIDC: Configurado para Bitbucket
+- Alcance: Repositorio `ccsoft1/proyectosacc`
+
+**Para producción:** Se debe crear un rol similar para el entorno prod.
+
+---
+
+## 🚀 PIPELINE CI/CD (7 Pasos)
+
+### Flujo del Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  RAMA DEVELOPER                                             │
+├─────────────────────────────────────────────────────────────┤
+│  01_image-setup        → Preparar imagen + SSH keys         │
+│  02_pre_terraform_check→ Limpiar locks de Terraform         │
+│  03_terraform          → Infraestructura (plan + apply)     │
+│  04_build              → Compilar frontend + backend        │
+│  05_publish            → Subir a S3                         │
+│  06_install            → Instalar JAR en servidor           │
+│  07_deploy             → Deploy + Invalidar CloudFront      │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│  RAMA MASTER (Producción)                                   │
+├─────────────────────────────────────────────────────────────┤
+│  01_image-setup        → Preparar imagen + SSH keys         │
+│  02_pre_terraform_check→ Limpiar locks de Terraform         │
+│  03_terraform          → Infraestructura (plan + apply)     │
+│  04_build              → Compilar frontend + backend        │
+│  05_publish            → Subir a S3                         │
+│  06_install            → Instalar JAR en servidor           │
+│  06b_notify_approval   → Notificar espera aprobación        │
+│  07_deploy             → Deploy manual (requiere aprobación)│
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Detalle de Steps
+
+#### Step 01: image-setup
+- Instala dependencias: openssh-client, openjdk-21-jdk, wget, unzip, curl
+- Instala AWS CLI v2
+- Configura llaves SSH para acceso al servidor
+- Configura notificaciones Telegram
+
+#### Step 02: pre_terraform_check
+- Instala AWS CLI
+- Configura credenciales OIDC
+- Ejecuta `terraform-lock-cleanup.sh`
+- **Previene errores de state lock**
+
+#### Step 03: terraform
+- Instala Terraform 1.11.4
+- Ejecuta `terraform init`
+- Ejecuta `terraform plan` (verificación)
+- Ejecuta `terraform apply` (crea/actualiza infraestructura)
+- Genera `terraform-outputs.json`
+
+#### Step 04: build
+- **Frontend:** Si existe `package.json` → `npm ci && npm run build`
+- **Backend:** Si existe `gradlew` → `./gradlew clean bootJar`
+- Genera artefactos: `build/**`, `build/libs/*.jar`
+
+#### Step 05: publish
+- Sincroniza `build/` con S3 frontend (`aws s3 sync`)
+- Copia JAR a S3 artifacts (`aws s3 cp`)
+
+#### Step 06: install
+- Descarga JAR desde S3 al servidor EC2
+- Configura permisos (`chown osiris:osiris`)
+
+#### Step 07: deploy
+- Ejecuta script de deploy en servidor EC2
+- Invalida distribución CloudFront
+- Notifica éxito por Telegram
+
+---
+
+## 🌐 INFRAESTRUCTURA AWS (Creada)
+
+### Recursos Activos
+
+| Servicio | Recurso | Identificador | Estado |
+|----------|---------|---------------|--------|
+| **EC2** | Instancia API | `i-044018f36de1020a8` | ✅ running |
+| | IP Pública | `78.12.135.184` | ✅ |
+| | DNS | `ec2-78-12-135-184.mx-central-1.compute.amazonaws.com` | ✅ |
+| **RDS** | Base de datos | `proyectosacc-db-dev` | ✅ available |
+| | Endpoint | `proyectosacc-db-dev.cbe2keowyu6w.mx-central-1.rds.amazonaws.com:3306` | ✅ |
+| | Motor | MariaDB | ✅ |
+| **S3** | Frontend | `ccsoft-proyectosacc-frontend-dev` | ✅ |
+| | Artifacts | `ccsoft-proyectosacc-artifacts-dev` | ✅ |
+| | Terraform State | `ccsoft-terraform-state` | ✅ |
+| **CloudFront** | Distribución | `E2EJ7237VFEJAR` | ✅ Deployed |
+| | Dominio | `d3donfm7ov3eyb.cloudfront.net` | ✅ |
+| **Route53** | Zona DNS | `dev-sacc.ccsoft.mx` | ✅ |
+| **VPC** | Red | `vpc-0fefbaa0848a316dd` (10.1.0.0/16) | ✅ |
+| **NAT Gateway** | Salida privada | `nat-0dafd3abd5557cd22` | ✅ |
+| **DynamoDB** | Locks Terraform | `terraform-locks` | ✅ |
+
+### Outputs de Terraform
+
+```json
+{
+  "ec2_public_ip": "78.12.135.184",
+  "ec2_public_dns": "ec2-78-12-135-184.mx-central-1.compute.amazonaws.com",
+  "rds_endpoint": "proyectosacc-db-dev.cbe2keowyu6w.mx-central-1.rds.amazonaws.com:3306",
+  "s3_frontend_bucket": "ccsoft-proyectosacc-frontend-dev",
+  "s3_artifacts_bucket": "ccsoft-proyectosacc-artifacts-dev",
+  "cloudfront_domain": "d3donfm7ov3eyb.cloudfront.net",
+  "cloudfront_distribution_id": "E2EJ7237VFEJAR",
+  "route53_record": "dev-sacc.ccsoft.mx",
+  "acm_certificate_arn": "arn:aws:acm:us-east-1:668889063715:certificate/521e3ae2-f22b-479f-a5ae-db9700caa248",
+  "vpc_id": "vpc-0fefbaa0848a316dd"
+}
+```
+
+---
+
+## 🔐 ACCESOS Y CREDENCIALES
+
+### Servidor EC2 (Desarrollo)
+
+```bash
+# Conexión SSH
+ssh -p 22 -i ~/.ssh/sacc4_key thoth@78.12.135.184
+
+# Usuarios configurados
+- thoth: Usuario de deploy (CI/CD)
+- osiris: Usuario de ejecución de la aplicación
+```
+
+### Base de Datos (RDS)
+
+```
+Host: proyectosacc-db-dev.cbe2keowyu6w.mx-central-1.rds.amazonaws.com
+Port: 3306
+Engine: MariaDB
+Usuario: *(configurado en Terraform)*
+Contraseña: ${DEV_DB_PASSWORD}
+```
+
+### S3 Buckets
+
+```bash
+# Frontend
+aws s3 ls s3://ccsoft-proyectosacc-frontend-dev/
+
+# Artifacts
+aws s3 ls s3://ccsoft-proyectosacc-artifacts-dev/
+```
+
+---
+
+## 📱 NOTIFICACIONES TELEGRAM
+
+### Bots Configurados
+- **@CCAlertasBot** - Alertas críticas
+- **@CCDevRoBot** - Notificaciones de desarrollo
+
+### Mensajes Enviados
+- ✅ Inicio de pipeline
+- ❌ Fallo de pipeline (con detalle del paso)
+- ✅ Deploy exitoso
+- ⏸️ Espera de aprobación (producción)
+
+---
+
+## 💰 COSTOS MENSUALES ESTIMADOS
+
+| Servicio | Costo Estimado |
+|----------|---------------|
+| EC2 t3.small | ~$15-20 |
+| RDS db.t3.micro | ~$15-20 |
+| NAT Gateway | ~$32 |
+| S3 (3 buckets) | ~$1-5 |
+| CloudFront | ~$1-10 |
+| Route53 | ~$0.50 |
+| Data Transfer | ~$5-10 |
+| **TOTAL** | **~$70-100/mes** |
+
+---
+
+## 🛠️ COMANDOS ÚTILES
+
+### Terraform (Local)
+
+```bash
+# Configurar credenciales
+export AWS_ACCESS_KEY_ID=...
+export AWS_SECRET_ACCESS_KEY=...
+export AWS_SESSION_TOKEN=...
+export AWS_DEFAULT_REGION=mx-central-1
+
+# Inicializar
+cd terraform
+terraform init -backend-config=backend.dev.hcl
+
+# Plan
+terraform plan -var-file=environments/dev.tfvars -var="db_password=TU_PASSWORD"
+
+# Apply
+terraform apply -var-file=environments/dev.tfvars -var="db_password=TU_PASSWORD"
+
+# Outputs
+terraform output -json
+```
+
+### AWS CLI
+
+```bash
+# Verificar identidad
+aws sts get-caller-identity
+
+# Listar instancias EC2
+aws ec2 describe-instances
+
+# Ver logs de CloudWatch
+aws logs tail /aws/lambda/... --follow
+
+# Invalidar CloudFront
+aws cloudfront create-invalidation --distribution-id E2EJ7237VFEJAR --paths "/*"
+```
+
+### Bitbucket Pipelines
+
+```bash
+# Ejecutar pipeline manualmente
+# Ir a: Bitbucket → Pipelines → Run pipeline
+# Seleccionar rama: developer o master
+```
+
+---
+
+## 🚨 TROUBLESHOOTING
+
+### Error: "Error acquiring the state lock"
+
+**Solución:** El pipeline ahora incluye el step `02_pre_terraform_check` que limpia locks automáticamente.
+
+### Error: "Saved plan is stale"
+
+**Solución:** El pipeline ahora ejecuta `plan` y `apply` sin guardar archivo intermedio.
+
+### Error: "aws: command not found"
+
+**Solución:** Cada step instala AWS CLI v2 independientemente.
+
+### Pipeline falla en step 07_deploy
+
+**Verificar:**
+1. Llave SSH está configurada en Bitbucket variables
+2. Servidor EC2 está running
+3. Script `/home/thoth/deploy/setup/deploy.sh` existe en servidor
+
+---
+
+## 📞 CONTACTOS Y SOPORTE
+
+| Rol | Contacto | Uso |
+|-----|----------|-----|
+| Infraestructura | Área de Tecnología | Credenciales, accesos AWS |
+| DevOps | Pipeline issues | Configuración CI/CD |
+| Seguridad | Rotación de llaves | SSH, tokens |
+
+---
+
+## ✅ CHECKLIST PARA DESARROLLO
+
+### Antes de hacer push
+
+- [ ] Código compila localmente (`npm run build` o `./gradlew bootJar`)
+- [ ] Tests pasan
+- [ ] Variables de entorno actualizadas (si aplica)
+
+### Después de merge a developer
+
+- [ ] Pipeline ejecuta automáticamente
+- [ ] Revisar notificación de Telegram
+- [ ] Verificar deploy en: https://dev-sacc.ccsoft.mx
+
+### Para producción (master)
+
+- [ ] Crear PR a master
+- [ ] Revisar plan de Terraform
+- [ ] Aprobar deploy manual en Bitbucket
+- [ ] Verificar en producción
+
+---
+
+## 📚 DOCUMENTACIÓN ADICIONAL
+
+- **Pipeline completo:** Ver `bitbucket-pipelines.yml`
+- **Scripts:** Ver carpeta `scripts/`
+- **Terraform:** Ver carpeta `terraform/`
+- **Directivas AWS:** Ver `docs/13-directivas-arquitectura-aws.md`
+
+---
+
+**Documento generado:** 17 Abril 2026
+**Versión:** 1.0
+**Mantenido por:** Área de Tecnología y Desarrollo - CCsoft