terraform-search-import
por hashicorpAprenda a usar o terraform-search-import para descobrir recursos de nuvem compatíveis com o Terraform Search e importá-los em massa para o estado do Terraform. Este skill terraform-search-import é útil para desenvolvimento de backend, auditorias e fluxos de migração quando você quer um guia prático para instalar, verificar o suporte do provider e começar a usar com menos tentativa e erro.
Este skill recebe 72/100 porque entrega valor real de fluxo de trabalho e tem evidências suficientes no repositório para ajudar usuários do diretório a decidir pela instalação. Ele deixa claro que atende a uma tarefa específica do Terraform — descobrir recursos compatíveis e importar em massa infraestrutura não gerenciada —, mas o fluxo é um pouco parcial e depende do suporte do Terraform/provider; por isso, espere um guia útil, porém não totalmente autossuficiente do ponto de vista operacional.
- Boa capacidade de ativação: a descrição e a seção "When to Use" miram com clareza descoberta de infraestrutura não gerenciada, auditoria e migração para o Terraform.
- Bom ganho operacional: inclui um script auxiliar para verificar o suporte do provider a list-resource, reduzindo a incerteza antes de tentar search/import.
- Conteúdo de fluxo confiável: faz referência à importação em massa e à orientação de fallback para importação manual, sem sinais de placeholder ou conteúdo só de teste.
- A execução depende do Terraform >= 1.14 e do suporte do provider a list-resource, então a aplicabilidade fica limitada pelo ambiente e pela capacidade do provider.
- A árvore de decisão e a referência à importação manual indicam caminhos alternativos, mas o fluxo principal parece complexo o suficiente para que os usuários ainda precisem de experiência com Terraform.
Visão geral da skill terraform-search-import
O que a terraform-search-import faz
A skill terraform-search-import ajuda você a descobrir recursos de cloud já existentes com consultas do Terraform Search e, em seguida, importá-los em lote para o state do Terraform. Ela é mais útil quando a infraestrutura já está em pé e você quer colocá-la sob controle do Terraform sem ter que mapear cada objeto manualmente.
Quem deve usar
A skill terraform-search-import é uma boa escolha para equipes de backend, engenheiros de plataforma e operadores que trabalham com migração, inventário ou governança. Ela faz mais diferença quando você precisa auditar recursos não gerenciados, padronizar o provisionamento ou sair de uma configuração manual de cloud para IaC com menos tentativas e erros.
Por que ela é diferente
A principal vantagem é começar pelo suporte do provider, e não por suposições. A skill verifica explicitamente se um tipo de recurso pode ser descoberto via Terraform Search antes de você seguir para um fluxo de importação em lote, o que reduz becos sem saída e prompts quebrados. Ela também aponta uma alternativa manual quando o provider não oferece suporte a list resources.
Como usar a skill terraform-search-import
Instale e verifique o ambiente
Use o comando de instalação da terraform-search-import a partir do contexto do repositório: npx skills add hashicorp/agent-skills --skill terraform-search-import. Depois confirme que o seu diretório de trabalho tem o Terraform inicializado, o terraform disponível e o jq instalado, porque o script auxiliar depende dos dois. A skill pressupõe Terraform >= 1.14 e uma versão do provider com suporte a list resource.
Comece pela checagem de suporte
Antes de pedir um plano de importação, execute ./scripts/list_resources.sh <provider> ou inspecione a mesma saída dentro do seu prompt. Essa é a forma mais rápida de descobrir se o Terraform Search consegue lidar com o tipo de objeto alvo. Se o recurso não aparecer na lista, mude para a referência de importação manual em vez de forçar o fluxo de busca.
Dê à skill um alvo de importação concreto
Prompts fortes nomeiam o provider, o tipo de recurso, o escopo e o objetivo. Por exemplo: “Use terraform-search-import para descobrir e importar em lote todos os recursos aws_s3_bucket em us-east-1 para a conta prod, depois mostre a query do Terraform Search e os passos de importação.” Entradas melhores reduzem ambiguidade sobre regiões, contas e se você quer apenas descoberta ou descoberta mais importação para o state.
Leia primeiro os arquivos certos
Para usar terraform-search-import na prática, comece por SKILL.md, depois references/MANUAL-IMPORT.md e, por fim, scripts/list_resources.sh. O SKILL.md traz o fluxo de trabalho, o MANUAL-IMPORT.md mostra o caminho de fallback para recursos sem suporte, e o script revela a checagem de capacidade do provider que a skill espera que você use.
Perguntas frequentes sobre a skill terraform-search-import
A terraform-search-import é só para importação em lote?
Não. Ela também é útil para descoberta de recursos e validação de suporte antes da importação. Se sua necessidade for apenas importar um único recurso uma vez, um fluxo normal de terraform import pode ser mais simples.
Quando não devo usar esta skill?
Não use terraform-search-import se o provider não expuser suporte a list resource para o tipo alvo, ou se você não puder executar terraform init no ambiente. Nesses casos, a orientação de importação manual é o melhor caminho.
Isso é amigável para iniciantes?
Sim, desde que você já saiba qual recurso de cloud quer gerenciar e consiga identificar o provider. A skill reduz o atrito de configuração, mas você ainda precisa de noções básicas de Terraform e do provider para interpretar a saída e confirmar o state importado.
Em que isso é diferente de um prompt genérico?
Um prompt genérico pode sugerir passos de importação sem checar a capacidade do provider ou os pré-requisitos da ferramenta. O guia terraform-search-import ancora o fluxo no suporte do Terraform Search, o que torna o resultado mais acionável e menos sujeito a falhar no fim.
Como melhorar a skill terraform-search-import
Forneça as entradas que realmente mudam o resultado
Os melhores resultados vêm de informar à skill o provider, o tipo exato de recurso, o escopo do ambiente e se você quer descoberta, importação ou ambos. Por exemplo, “Encontre todos os recursos azurerm_storage_account suportados na subscription dev e depois prepare instruções de importação em lote” é muito melhor do que “importe meus recursos de cloud”.
Fique atento ao modo de falha mais comum
A maior falha é tentar usar terraform-search-import em recursos sem suporte. Se a checagem de suporte não retornar nada, pare e use references/MANUAL-IMPORT.md em vez de tentar forçar uma solução baseada em busca. Isso economiza tempo e mantém o fluxo alinhado com as capacidades reais do provider.
Itere da descoberta para a importação
Um bom fluxo é: verificar suporte, listar recursos, escolher um escopo estreito e só então expandir para o conjunto completo depois que o primeiro recurso parecer correto. Essa sequência ajuda você a capturar divergências de nomenclatura, permissões ausentes e desvio de região ou conta antes que a importação em lote gere um state poluído.
Melhore os prompts com detalhes reais do inventário
Quando você já conhece nomes de exemplo de recursos, ARNs, IDs ou limites de conta e região, inclua esses dados. Esses detalhes ajudam a terraform-search-import a produzir uma query mais precisa e um plano de importação mais seguro, especialmente em ambientes de backend onde o mesmo tipo de recurso pode existir em várias etapas.