Cómo importar recursos existentes a OpenTofu: CLI frente a bloques import (tutorial de Spacelift)

El artículo, publicado en el blog de Spacelift, es un tutorial práctico sobre cómo incorporar a OpenTofu infraestructura que ya existe fuera de tu proceso de infraestructura como código (IaC). Aviso al lector: el texto recibido está truncado a mitad de la sección sobre la generación automática de configuración con -generate-config-out, así que este resumen cubre solo lo que aparece en esa parte del contenido y no las secciones finales (errores comunes, buenas prácticas, gestión a escala con Spacelift y conclusiones).

El planteamiento de partida es que casi cualquier entorno tiene recursos creados a mano, con scripts a medida o con otras herramientas. Importar significa enlazar un recurso real del proveedor con un recurso de OpenTofu: si la operación tiene éxito, el archivo de estado guarda los atributos del objeto y su ciclo de vida pasa a gestionarse desde OpenTofu como cualquier otro recurso. El artículo enumera los casos de uso más habituales: infraestructura creada manualmente o con scripts, migraciones desde herramientas como CloudFormation, Pulumi, Crossplane o Azure Bicep, recuperación de estado tras borrados accidentales o corrupción, división de un estado grande en configuraciones más pequeñas y cambios de emergencia hechos a mano.

Se describen dos mecanismos. El primero es el comando de CLI tofu import, heredado de Terraform, que recibe una dirección de recurso y un ID del proveedor y escribe en el estado de inmediato, sin plan, previsualización ni aprobación. El segundo es el bloque import, que se escribe en la configuración, se evalúa en tofu plan (mostrando exactamente qué ocurrirá) y se ejecuta en tofu apply. Según el artículo, el bloque import existe desde OpenTofu 1.6, incorporó for_each en la 1.7 y el argumento identity en la 1.12. Este último sirve sobre todo para recursos cuyo identificador es una clave compuesta.

Como requisitos previos, el autor menciona usar una versión de OpenTofu que soporte las capacidades necesarias, tener configurado el proveedor, un backend remoto en entornos de producción y permisos de lectura sobre los recursos, además de comprobar que el tipo de recurso admite importación. Para localizar el ID correcto recomienda consultar siempre la sección «Import» al final de la página del recurso en el registro de OpenTofu. Algunos recursos se importan con un ID simple, como una instancia EC2, y otros requieren una clave compuesta, como aws_security_group_rule, que combina el ID del grupo de seguridad, el tipo de regla, el protocolo, los puertos y el origen unidos por guiones bajos.

En el método 1 (CLI), la sintaxis es tofu import [opciones] ADDR ID. La dirección puede apuntar a recursos de la raíz, dentro de módulos o a instancias concretas con count o for_each, por ejemplo module.networking.aws_vpc.main, aws_vpc.main[0] o aws_vpc.main["london"], con la nota de que en algunos sistemas operativos hay que escapar las comillas dobles. El ejemplo crea un bucket S3 con la AWS CLI, declara un recurso aws_s3_bucket con el mismo nombre, ejecuta tofu init e importa usando el nombre del bucket como ID. Después, tofu state list muestra el recurso y tofu plan indica que no hay cambios. Entre las opciones útiles se citan -config, -var y -var-file, -no-color (útil en logs de CI) y -input=false para evitar preguntas interactivas.

El autor enumera las limitaciones de la vía CLI, y por eso recomienda el bloque import: solo importa un objeto por invocación (50 recursos implican 50 ejecuciones), no hay previsualización y modifica el estado directamente (si te equivocas de dirección hay que eliminar el recurso del estado y volver a empezar), no genera configuración, no deja constancia en el código de que algo fue importado y encaja mal en pipelines de CI/CD porque exige añadir un paso de importación y retirarlo después.

En el método 2, el bloque import usa el argumento to (la dirección del recurso destino) y id o identity. El bloque solo está activo mientras OpenTofu no rastree ya un objeto en esa dirección, así que puede conservarse como registro histórico o borrarse. Se recomienda colocarlo en un archivo imports.tf dedicado o junto al recurso. El argumento id es el enfoque clásico (una cadena en el formato que espere el proveedor), mientras que identity, disponible desde la 1.12, usa un objeto cuyos atributos provienen del esquema de identidad del tipo de recurso. También se puede usar el metaargumento provider cuando hay varios proveedores con alias, para decidir con qué credenciales y región se busca e importa el recurso.

En el ejemplo paso a paso, tras init, tofu plan muestra «Plan: 1 to import, 0 to add, 0 to change, 0 to destroy» y detalla los atributos del bucket; tofu apply termina con «1 imported». Si se vuelve a ejecutar apply sin quitar el bloque, no hay cambios. Para importar varios recursos, el artículo crea un segundo bucket y combina una variable con la lista de nombres, un recurso aws_s3_bucket con for_each y un bloque import con for_each que usa each.value tanto en la dirección to como en identity. El resultado es «2 imported».

Las ventajas que se resumen para los bloques import son: queda historial de qué se importó y qué se creó con OpenTofu, se pueden importar varios recursos con un solo bloque mediante for_each, hay previsualización con tofu plan antes de mutar nada (lo que lo hace apto para CI) y es posible generar la configuración automáticamente.

Por último, el texto introduce la opción tofu plan -generate-config-out=generated_resources.tf, que escribe la configuración del recurso por ti a partir de un bloque import. El artículo advierte de que es una función todavía experimental y de que no funciona con recursos que usen for_each o count. La descripción del resultado queda cortada en este punto. En conjunto, el mensaje central es claro: usar bloques import en lugar del comando de CLI, comprobar el ID de importación en el registro y revisar siempre el plan antes de aplicar.