Saltar al contenido principal

Despliegue y Consideraciones Operativas

🎯 Objetivo​

Regla​

16.1: Se debe establecer un proceso de despliegue automatizado, repetible y seguro para las APIs REST. 16.2: Se deben implementar prácticas operativas robustas, incluyendo monitorización, logging y gestión de la configuración, para asegurar la fiabilidad y mantenibilidad de la API en producción.

📖 Concepto y Definición​

Regla​

16.3: Despliegue Automatizado: Proceso obligatorio de llevar nuevas versiones de la API a los diferentes entornos (desarrollo, staging, producción) usando herramientas y scripts, minimizando la intervención manual. 16.4: Integración Continua (CI): Práctica obligatoria donde los cambios de código se integran y verifican automáticamente (construcción, pruebas unitarias/integración/contrato) con frecuencia. 16.5: Entrega Continua (CD): Extensión de CI donde los cambios que pasan las pruebas son automáticamente preparados para ser desplegados a producción (puede requerir aprobación manual). 16.6: Despliegue Continuo (CD): Extensión de Entrega Continua donde los cambios que pasan todas las etapas se despliegan automáticamente a producción. 16.7: Monitorización: Proceso obligatorio de observar el comportamiento y rendimiento de la API en producción (tasas de error, latencia, uso de recursos, tráfico). 16.8: Logging: Registro obligatorio de eventos relevantes (solicitudes, errores, eventos de negocio) para diagnóstico y auditoría. 16.9: Gestión de Configuración: Manejo obligatorio de la configuración de la aplicación (ej. credenciales de BD, claves API externas, niveles de log) de forma segura y separada del código base.

🤔 ¿Por qué es Importante? / Beneficios Clave (Contexto)​

  • Despliegues Rápidos y Fiables: Reduce el riesgo y el tiempo de entrega.
  • Consistencia entre Entornos: Evita problemas de "funciona en mi máquina".
  • Recuperación Rápida: Facilita el rollback en caso de problemas.
  • Visibilidad Operativa: Permite entender cómo se comporta la API.
  • Diagnóstico Eficaz: Facilita la identificación y resolución de problemas.
  • Seguridad: Manejo seguro de configuraciones sensibles.

✅ Buenas Prácticas y Recomendaciones Clave​

Despliegue (CI/CD):​

Regla​

16.10: Se debe implementar un pipeline de CI/CD completo que incluya:

  • Checkout de código.
  • Instalación de dependencias.
  • Análisis estático de código (Linting).
  • Ejecución de pruebas automatizadas (unitarias, integración, contrato - ver Sección 15).
  • Construcción de artefactos (ej. imagen Docker).
  • Despliegue a entornos inferiores (ej. staging).
  • (Opcional/Recomendado) Pruebas adicionales en staging (E2E, carga).
  • Despliegue a producción (manual o automático según política). 16.11: Se deben usar estrategias de despliegue que minimicen el tiempo de inactividad y el riesgo, como:
  • Blue-Green Deployment: Mantener dos entornos de producción idénticos, redirigiendo el tráfico al nuevo una vez verificado.
  • Canary Release: Liberar la nueva versión a un pequeño subconjunto de usuarios antes de extenderla a todos.
  • Rolling Update: Actualizar instancias gradualmente. 16.12: El proceso de rollback a una versión anterior debe ser rápido y automatizado. 16.13: La infraestructura (servidores, bases de datos, balanceadores) debe ser gestionada como código (IaC) usando herramientas como Terraform o CloudFormation para asegurar consistencia y repetibilidad.

Operaciones (Monitorización, Logging, Configuración):​

Regla​

16.14: La monitorización debe cubrir como mínimo:

  • Métricas de Sistema: Uso de CPU, memoria, disco, red de las instancias de servidor.
  • Métricas de Aplicación: Tasa de solicitudes (throughput), latencia por endpoint, tasa de errores (total y por código de estado/endpoint).
  • Salud de Dependencias: Estado de bases de datos, cachés, servicios externos. 16.15: Se deben configurar alertas automáticas para métricas críticas que excedan umbrales predefinidos (ej. alta tasa de errores 5xx, latencia elevada, bajo espacio en disco). 16.16: El logging debe ser estructurado (preferiblemente JSON) para facilitar el análisis y la consulta. 16.17: Los logs deben incluir información contextual relevante como:
  • Timestamp.
  • Nivel de severidad (INFO, WARN, ERROR, etc.).
  • Identificador de solicitud único (correlation ID) para rastrear una solicitud a través de diferentes servicios/componentes.
  • Endpoint, método HTTP.
  • Identificador de usuario (si aplica y es seguro loguearlo).
  • Mensaje de log claro.
  • Stack trace completo para errores (solo en logs, no en respuesta al cliente). 16.18: Nunca se deben loguear datos sensibles en claro (contraseñas, tokens de sesión completos, números de tarjeta de crédito, datos personales). Se deben aplicar técnicas de enmascaramiento o evitar su logueo. 16.19: Los logs deben ser centralizados en un sistema dedicado (ej. ELK stack, Splunk, Datadog Logs, CloudWatch Logs) para facilitar la búsqueda y el análisis. 16.20: La configuración de la aplicación (credenciales, endpoints externos, flags de funcionalidad) debe gestionarse fuera del código fuente. 16.21: Se debe utilizar un sistema seguro para gestionar secretos (ej. Vault, AWS Secrets Manager, Azure Key Vault, variables de entorno inyectadas de forma segura). 16.22: La configuración debe ser específica para cada entorno (desarrollo, staging, producción).

Don'ts (Prohibido):

  • 16.23: No se debe realizar despliegues manuales a producción si se puede automatizar.
  • 16.24: No se debe desplegar sin haber ejecutado y pasado las pruebas automatizadas.
  • 16.25: No se debe operar una API en producción sin monitorización y alertas adecuadas.
  • 16.26: No se deben loguear datos sensibles.
  • 16.27: No se deben almacenar secretos o configuraciones específicas de entorno en el control de versiones (Git).

💡 Ejemplos Prácticos (Ilustrativos)​

Ejemplo 1: Pipeline CI/CD Básico (Conceptual)​

  1. Commit a Git: Desarrollador hace push.
  2. Trigger CI (Jenkins, GitLab CI, GitHub Actions):
    • Linting.
    • Pruebas Unitarias.
    • Pruebas de Integración.
    • Pruebas de Contrato (vs OAS).
    • Construir Imagen Docker.
    • Push a Registro Docker.
  3. Trigger CD (Opcional: Aprobación Manual):
    • Desplegar Imagen a Staging.
    • (Ejecutar Pruebas E2E en Staging).
  4. Trigger CD (Opcional: Aprobación Manual):
    • Desplegar Imagen a Producción (usando Blue-Green/Canary/Rolling).

Ejemplo 2: Log Estructurado (JSON) (Norma 16.16, 16.17)​

{
  "timestamp": "2023-10-27T14:15:30.123Z",
  "level": "ERROR",
  "message": "Fallo al procesar el pago para la orden.",
  "correlationId": "req-xyz789",
  "userId": "user-abc",
  "orderId": "ord-123",
  "endpoint": "POST /v1/payments",
  "error": {
    "code": "PAYMENT_PROVIDER_UNAVAILABLE",
    "details": "Timeout contactando al proveedor de pagos."
  },
  "stacktrace": "... stack trace completo ..." // Solo en logs
}

Ejemplo 3: Gestión de Secretos (Conceptual)​

  • En lugar de: const apiKey = "SECRET_KEY_IN_CODE"; (Prohibido - Norma 16.27)
  • Usar: const apiKey = process.env.PAYMENT_API_KEY;
  • La variable de entorno PAYMENT_API_KEY debe ser inyectada de forma segura en el entorno de ejecución por el sistema de despliegue o un gestor de secretos, no almacenada en Git.

🛠️ Herramientas y Consideraciones Adicionales (Contexto)​

  • CI/CD: Jenkins, GitLab CI/CD, GitHub Actions, CircleCI, Azure DevOps.
  • IaC: Terraform, Pulumi, AWS CloudFormation, Azure Resource Manager.
  • Monitorización/APM: Datadog, New Relic, Dynatrace, Prometheus + Grafana, AWS CloudWatch.
  • Logging Centralizado: ELK Stack (Elasticsearch, Logstash, Kibana), Splunk, Graylog, Datadog Logs, Loki.
  • Gestión de Secretos: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, Google Secret Manager.
  • Contenedorización: Docker, Kubernetes.
  • Feature Flags: Herramientas como LaunchDarkly o bibliotecas internas pueden ayudar a desacoplar el despliegue de la liberación de funcionalidades.