Contexto y objetivo

Una API en producción servía una plataforma con varios entornos que partían de versiones distintas de PHP (producción en 8.1, staging en 8.3, desarrollo en 8.4). El salto a Laravel 13 + PHP 8.5 tocaba la capa de instancia (runtime, servicios) y el mecanismo de despliegue (CodeDeploy), no solo el código. Un cambio así, hecho a ciegas en producción, es de los que tumban un servicio entero.

Por eso decidí validar primero el runtime y el despliegue en una instancia viva de desarrollo, sacar a la luz todos los ajustes necesarios y solo después industrializar el resultado en AMI + Terraform para promoverlo a staging y producción con el mínimo de decisiones en caliente.

Enfoque en dos fases

La decisión clave fue separar explícitamente dos fases en lugar de mezclarlas:

• Fase 1 — validación manual guiada por runbook: ejecutar el cambio sobre una instancia de desarrollo desechable, con baseline, checkpoints, validaciones intermedias y un rollback definido. Prioriza la velocidad de aprendizaje real sobre instancia viva.
• Fase 2 — estandarización declarativa: convertir lo aprendido en AMI, hooks de CodeDeploy endurecidos y módulos de Terraform, para que el cambio sea repetible y no nazca como configuración manual.

Descarté industrializar directamente en Terraform: habría mezclado la validación funcional con la estandarización de plataforma y metido demasiadas variables a la vez sobre supuestos sin verificar.

Estrategia técnica: dos bloques de aceptación

Estructuré la validación en dos puertas, con la regla de no avanzar si la primera falla:

• Bloque A — salud de plataforma: PHP 8.5 instalado y activo, CLI y PHP-FPM alineados en la misma versión, extensiones requeridas presentes, y arranque correcto de Nginx, php-fpm, Redis, Supervisor y el agente de CodeDeploy, sin referencias rotas a versiones anteriores en configs, sockets o scripts.
• Bloque B — salud de aplicación y despliegue: CodeDeploy despliega el artefacto de Laravel 13 con sus hooks sin fallos, y artisan, caches, colas, scheduler y logs funcionan con el nuevo runtime.

Orden de ejecución

• Baseline pre-cambio y preparación del rollback.
• Upgrade manual del runtime a PHP 8.5 y adaptación de servicios asociados.
• Validación técnica de plataforma (Bloque A).
• Despliegue real por CodeDeploy y validación post-deploy de Laravel 13 (Bloque B).
• Observación operativa corta y consolidación documental de hallazgos.

Riesgos anticipados

Partí de los puntos donde un upgrade de runtime suele romperse, para vigilarlos activamente en lugar de descubrirlos en producción:

• Desalineación entre PHP CLI y PHP-FPM, o extensiones faltantes en 8.5.
• Cambio de socket o servicio php-fpm no reflejado en Nginx.
• Hooks de CodeDeploy con rutas o binarios hardcodeados a la versión antigua.
• Configs de Supervisor o scripts auxiliares que asumen otra versión de PHP.
• Permisos sobre storage y bootstrap/cache; degradación de colas, scheduler o sesiones por Redis; caches generadas en contexto incorrecto.

Entregables

• Runbook de ejecución paso a paso (alcance, prerequisitos, baseline, comandos exactos, checkpoints, criterios de parada y rollback).
• Checklist de validación post-upgrade con resultado pass/fail por ítem y evidencias, para no dar el cambio por bueno por percepción.
• Documento de hallazgos que clasifica cada ajuste según deba ir a AMI, a Terraform, a hooks/bootstrap de CodeDeploy o parametrizarse, conectando la fase manual con la declarativa.

Resultado e impacto

• Migración de runtime ejecutada de forma controlada y trazable, con CodeDeploy compatible con el nuevo runtime de extremo a extremo.
• Proceso repetible: staging se usa como validación de repetibilidad y producción ejecuta un procedimiento ya depurado, con las diferencias entre entornos documentadas antes de promover.
• Base sólida para construir una AMI válida y traducir el cambio a Terraform apoyándose en hechos verificados, no en supuestos.