labadmin/proyectosacc-mirror
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
proyectosacc-mirror/GUIA_DESARROLLO.md
T
Evert Daniel Romero Garrido defce6933d 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

400 lines
14 KiB
Markdown
Raw Permalink Blame History

# 📋 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
Reference in New Issue View Git Blame Copy Permalink