A veces necesitas mover el estado de un sitio a otro: pasar de estado local a remoto, cambiar de bucket, reorganizar tu proyecto, o fusionar configuraciones. La migración de estado es una operación delicada pero habitual, y conviene saber hacerla bien para no perder ni corromper tu «fuente de la verdad». En este subcapítulo veremos cómo migrar el estado de forma segura.

Recuerda que el estado es el registro de qué infraestructura existe (Capítulo 11). Hay varias situaciones reales en las que necesitas moverlo:

• De local a remoto: empezaste con estado local (en tu portátil) y ahora quieres pasarlo a un backend S3 compartido (subcapítulo 20.1) para trabajar en equipo. Es el caso más común.
• Cambio de backend: mueves el estado de un bucket a otro, o de un sistema a otro (por ejemplo, a Terraform Cloud, Capítulo 22).
• Reorganización del proyecto: divides un proyecto grande en varios más pequeños, o fusionas varios en uno, lo que implica mover recursos entre estados.

Esta es la migración más frecuente y, afortunadamente, Terraform la hace casi automática. El proceso:

Cuando ejecutas terraform init tras añadir el backend, Terraform es lo bastante inteligente como para darse cuenta de que tienes un estado local y ofrecerte copiarlo al nuevo destino:

Respondes yes y Terraform copia el estado al backend remoto. A partir de ahí, trabaja desde S3.

Si ya tienes un backend remoto y quieres cambiarlo (por ejemplo, otro bucket), el proceso es similar:

La opción -migrate-state le indica explícitamente a Terraform que quieres mover el estado al nuevo backend, no empezar de cero.

A veces no quieres mover todo el estado, sino recursos concretos de un proyecto a otro (por ejemplo, al dividir un proyecto grande). Para eso existe el comando terraform state mv, que reubica un recurso dentro del estado o hacia otro:

Esto le dice a Terraform: «este recurso ahora vive en otro sitio del estado, pero es el mismo recurso real; no lo destruyas ni lo recrees, solo actualiza su registro». Es muy útil al refactorizar (por ejemplo, al meter recursos sueltos dentro de un módulo, Capítulo 18).

Por qué importa state mv: sin él, si reorganizas tu código y Terraform «pierde» de vista un recurso, podría pensar que ya no existe y querer destruirlo y crear otro nuevo. state mv evita ese destrozo: le dices «es el mismo, solo cambió de nombre/ubicación en el código».

La migración de estado toca tu «fuente de la verdad», así que la prudencia es esencial. Sigue siempre estas reglas:

Antes de cualquier migración, guarda una copia del estado actual. Si algo sale mal, puedes restaurarlo. Si tu bucket S3 tiene versionado activado (subcapítulo 20.1), ya tienes ese historial, pero una copia manual extra nunca está de más.

Durante la migración, nadie más debe estar ejecutando Terraform sobre ese estado. Coordínate con tu equipo (recuerda el locking del subcapítulo 20.2: la migración también necesita que el estado no esté en uso).

Tras la migración, ejecuta terraform plan. Si la migración fue correcta, el plan debe mostrar «sin cambios» (No changes): eso confirma que el estado nuevo refleja exactamente la infraestructura real, sin haber perdido ni alterado nada.

El archivo de estado es un JSON, pero no lo edites manualmente salvo en emergencias extremas y sabiendo muy bien lo que haces. Usa siempre los comandos de Terraform (state mv, state rm, init -migrate-state), que conocen su estructura interna y evitan corromperlo.

• Migrar el estado (moverlo de sitio) es necesario al pasar de local a remoto, cambiar de backend o reorganizar el proyecto.
• Local → remoto: añades el bloque backend y ejecutas terraform init; Terraform detecta el estado local y te ofrece copiarlo (respondes yes). Es casi automático.
• Remoto → otro remoto: cambias la configuración y usas terraform init -migrate-state.
• Para mover recursos concretos dentro del estado (al refactorizar), usa terraform state mv, que evita que Terraform destruya y recree un recurso que solo cambió de ubicación en el código.
• Reglas de oro: haz copia de seguridad antes, avisa al equipo (nadie más trabajando), verifica con plan después (debe decir «sin cambios») y nunca edites el estado a mano.

En el último subcapítulo del capítulo veremos una operación muy relacionada y muy útil: terraform import, para traer al estado recursos que ya existen en AWS pero que Terraform aún no gestiona.