AWS CDK Migrate como converti un CloudFormation legacy a CDK en un dia

cdk migrate es un comando que salió hace un tiempo y que muchos no conocen. Convierte CloudFormation existente a código CDK. Lo usé hace poco en un proyecto heredado y quiero contar cómo me fue.

El escenario

Heredé un stack de CloudFormation de unas 800 líneas de YAML. Funcionaba, pero cada cambio tomaba mucho tiempo porque nadie quería tocar el archivo. El equipo decidió migrar a CDK para poder usar TypeScript y separar responsabilidades.

El comando

cdk migrate \
  --stack-name mi-stack-legacy \
  --from-stack \
  --language typescript

Esto toma el stack desplegado, descarga su plantilla, y genera código CDK equivalente.

Lo que genera

Un proyecto CDK completo con un stack que replica exactamente lo que había. No es código bonito. Es código funcional que refleja la estructura del YAML original.

Lo que hice después

1. Refactoricé por responsabilidad. El stack monolítico lo partí en tres: red, datos, cómputo.
2. Reemplacé recursos L1 por L2. CDK migrate genera muchos CfnX crudos porque es la traducción más segura. Los cambié por constructs L2 cuando tenía sentido.
3. Agregué tests. Usando aws-cdk-lib/assertions para validar que la estructura se mantenía.
4. Hice cdk diff. Este paso es crítico. Me aseguró que mi código nuevo generaba exactamente el mismo CloudFormation que el stack existente. Cero cambios de drift.

El paso que no te puedes saltar

Antes de hacer cdk deploy por primera vez sobre el stack migrado, toca importar los recursos. CDK migrate te da las instrucciones, pero resumido:

1. Despliegas el nuevo stack CDK en modo "resource import".
2. Asocia los recursos existentes al nuevo stack.
3. Eliminas el stack viejo sin tocar los recursos.

Este paso lo probé primero en un ambiente de pruebas. No lo hagas directo en producción sin ensayar.

Lo que no migra bien

• Recursos con nombres autogenerados son un dolor porque hay que preservar el nombre.
• Outputs que otros stacks consumen requieren cuidado extra.
• Custom resources con Lambdas asociadas a veces necesitan retoque manual.

Cierre

cdk migrate no es mágico, pero es un punto de partida decente. Te ahorra escribir desde cero el esqueleto del stack y puedes concentrarte en el refactor, que es donde está el valor real.