terraform-search-import

Descripción general de la skill terraform-search-import

Qué hace terraform-search-import

La skill terraform-search-import te ayuda a descubrir recursos cloud existentes con consultas de Terraform Search y luego importarlos en bloque al estado de Terraform. Es especialmente útil cuando ya tienes infraestructura en marcha y quieres llevarla al control de Terraform sin tener que mapear a mano cada objeto.

Quién debería usarla

La skill terraform-search-import encaja bien con equipos de backend, ingenieros de plataforma y operadores que trabajan en tareas de migración, inventario o gobernanza. Resulta más valiosa cuando necesitas auditar recursos no gestionados, estandarizar el aprovisionamiento o pasar de una configuración manual en la nube a IaC con menos incertidumbre.

Por qué es diferente

La principal ventaja es que parte del soporte del proveedor, no de suposiciones. La skill comprueba explícitamente si un tipo de recurso puede descubrirse mediante Terraform Search antes de que te lances a una ruta de importación masiva, lo que reduce callejones sin salida y prompts rotos. También te orienta hacia una alternativa manual cuando el proveedor no admite recursos de lista.

Cómo usar la skill terraform-search-import

Instala y verifica el entorno

Usa el comando de instalación de terraform-search-import desde el contexto del repositorio: npx skills add hashicorp/agent-skills --skill terraform-search-import. Después confirma que tu directorio de trabajo tenga Terraform inicializado, terraform disponible y jq instalado, porque el script auxiliar depende de ambos. La skill asume Terraform >= 1.14 y una versión del proveedor con soporte para recursos de lista.

Empieza por la comprobación de compatibilidad

Antes de pedir un plan de importación, ejecuta ./scripts/list_resources.sh <provider> o inspecciona ese mismo resultado dentro de tu prompt. Es la forma más rápida de saber si Terraform Search puede gestionar el tipo de objeto que buscas. Si el recurso no aparece, cambia a la referencia de importación manual en lugar de forzar el flujo basado en búsqueda.

Dale a la skill un objetivo de importación concreto

Los prompts sólidos nombran el proveedor, el tipo de recurso, el alcance y el objetivo. Por ejemplo: “Usa terraform-search-import para descubrir e importar en bloque todos los recursos aws_s3_bucket en us-east-1 para la cuenta prod, y luego muestra la consulta de Terraform Search y los pasos de importación.” Cuanto más precisas sean las entradas, menos ambigüedad habrá sobre regiones, cuentas y si quieres solo descubrimiento o descubrimiento más importación al estado.

Lee primero los archivos adecuados

Para usar terraform-search-import de forma práctica, empieza por SKILL.md, luego references/MANUAL-IMPORT.md y finalmente scripts/list_resources.sh. SKILL.md explica el flujo de trabajo, MANUAL-IMPORT.md muestra la ruta alternativa para recursos no compatibles y el script revela la comprobación de capacidades del proveedor que la skill espera que uses.

Preguntas frecuentes sobre la skill terraform-search-import

¿terraform-search-import es solo para importación masiva?

No. También es útil para descubrir recursos y validar compatibilidad antes de importar. Si solo necesitas importar una vez un único recurso, un flujo normal de terraform import puede ser más sencillo.

¿Cuándo no debería usar esta skill?

No uses terraform-search-import si el proveedor no expone soporte de recursos de lista para el tipo que te interesa, o si no puedes ejecutar terraform init en el entorno. En esos casos, la guía de importación manual encaja mejor.

¿Es apta para principiantes?

Sí, siempre que ya conozcas el recurso cloud que quieres gestionar y puedas identificar el proveedor. La skill reduce la fricción de configuración, pero aun así necesitas nociones básicas de Terraform y del proveedor para interpretar la salida y confirmar el estado importado.

¿En qué se diferencia de un prompt genérico?

Un prompt genérico puede sugerir pasos de importación sin comprobar la capacidad del proveedor ni los requisitos de las herramientas. La guía terraform-search-import ancla el flujo en el soporte de Terraform Search, lo que hace que el resultado sea más accionable y menos propenso a fallar al final.

Cómo mejorar la skill terraform-search-import

Aporta los datos que realmente cambian el resultado

Los mejores resultados llegan cuando le dices a la skill el proveedor, el tipo exacto de recurso, el alcance del entorno y si quieres descubrimiento, importación o ambas cosas. Por ejemplo, “Encuentra todos los recursos compatibles azurerm_storage_account en la suscripción dev y prepara instrucciones de importación masiva” es mucho mejor que “importa mis recursos cloud”.

Vigila el modo de fallo más común

El fallo principal es intentar usar terraform-search-import con recursos no compatibles. Si la comprobación de soporte no devuelve nada, detente y usa references/MANUAL-IMPORT.md en lugar de forzar una solución basada en búsqueda. Así ahorras tiempo y mantienes el flujo alineado con las capacidades reales del proveedor.

Itera del descubrimiento a la importación

Un buen flujo de trabajo es: verificar compatibilidad, listar recursos, elegir un alcance reducido y luego ampliar al conjunto completo solo después de que el primer recurso parezca correcto. Esa secuencia te ayuda a detectar discrepancias de nombres, permisos faltantes y desajustes de región o cuenta antes de que una importación masiva genere un estado ruidoso.

Mejora los prompts con datos reales de inventario

Cuando ya conoces nombres de ejemplo de recursos, ARNs, IDs o límites de cuenta y región, inclúyelos. Esos detalles ayudan a que terraform-search-import genere una consulta más precisa y un plan de importación más seguro, especialmente en entornos de backend donde el mismo tipo de recurso puede existir en varias etapas.