terraform-search-import

terraform-search-import skill 개요

terraform-search-import가 하는 일

terraform-search-import skill은 Terraform Search 쿼리로 기존 클라우드 리소스를 찾아낸 뒤, 이를 Terraform state로 대량 import할 수 있게 도와줍니다. 이미 인프라가 구축되어 있고, 하나하나 객체를 수동 매핑하지 않고도 Terraform 관리 아래로 가져오고 싶을 때 가장 유용합니다.

누가 사용하면 좋은가

이 terraform-search-import skill은 백엔드 개발팀, 플랫폼 엔지니어, 운영 담당자처럼 마이그레이션, 인벤토리 정리, 거버넌스 작업을 하는 사용자에게 잘 맞습니다. 특히 관리되지 않는 리소스를 감사하거나, 프로비저닝 방식을 표준화하거나, 수작업 클라우드 구성을 IaC로 옮기되 추측을 줄이고 싶을 때 중요합니다.

무엇이 다른가

가장 큰 장점은 가정을 먼저 세우는 방식이 아니라 provider 지원 여부부터 확인한다는 점입니다. 이 skill은 bulk import 경로로 들어가기 전에 해당 resource type이 Terraform Search로 발견 가능한지 명시적으로 검사하므로, 되돌아갈 길 없는 막다른 선택지나 깨진 프롬프트를 줄여줍니다. 또한 provider가 list resources를 지원하지 않을 때는 manual fallback으로 자연스럽게 안내합니다.

terraform-search-import skill 사용 방법

설치하고 환경을 확인하기

repo 컨텍스트에서 terraform-search-import install command를 사용하세요: npx skills add hashicorp/agent-skills --skill terraform-search-import. 그다음 작업 디렉터리에 Terraform 초기화가 되어 있는지, terraform를 사용할 수 있는지, 그리고 jq가 설치되어 있는지 확인해야 합니다. helper script가 이 둘에 의존하기 때문입니다. 이 skill은 Terraform >= 1.14와 list resource 지원이 있는 provider version을 전제로 합니다.

먼저 지원 여부부터 확인하기

import plan을 요청하기 전에 ./scripts/list_resources.sh <provider>를 실행하거나, 같은 출력 내용을 프롬프트에 반영하세요. 이것이 Terraform Search가 대상 object type을 처리할 수 있는지 가장 빠르게 확인하는 방법입니다. resource가 목록에 없다면 search workflow를 억지로 밀어붙이지 말고 manual import reference로 전환하세요.

skill에 구체적인 import 대상을 주기

좋은 프롬프트는 provider, resource type, scope, 목표를 함께 명시합니다. 예를 들어: “terraform-search-import를 사용해 account prod의 us-east-1에서 모든 aws_s3_bucket resources를 찾아 bulk import하고, Terraform Search query와 import steps까지 보여줘.”처럼 요청할 수 있습니다. 입력이 구체적일수록 region, account, discovery만 할지 discovery plus state import까지 할지에 대한 모호함이 줄어듭니다.

먼저 읽어야 할 파일을 정확히 고르기

실제로 terraform-search-import를 사용할 때는 SKILL.md부터 시작하고, 그다음 references/MANUAL-IMPORT.md, 마지막으로 scripts/list_resources.sh를 보세요. SKILL.md는 전체 workflow를 설명하고, MANUAL-IMPORT.md는 지원되지 않는 resource를 위한 fallback 경로를 보여주며, script는 skill이 기대하는 provider capability check를 확인하게 해줍니다.

terraform-search-import skill FAQ

terraform-search-import는 bulk import에만 쓰는 건가요?

아닙니다. import 전에 resource discovery와 support validation에도 유용합니다. 단일 resource 하나를 한 번만 import하면 되는 상황이라면, 일반적인 Terraform import workflow가 더 단순할 수 있습니다.

언제 이 skill을 쓰지 말아야 하나요?

대상 type에 대해 provider가 list resource support를 제공하지 않거나, 환경에서 terraform init을 실행할 수 없다면 terraform-search-import를 사용하지 마세요. 이런 경우에는 manual import guidance가 더 적합합니다.

초보자도 쓰기 쉬운가요?

관리하려는 cloud resource를 이미 알고 있고 provider를 식별할 수 있다면 그렇습니다. 이 skill은 setup friction을 줄여주지만, 출력 결과를 해석하고 imported state를 확인하려면 기본적인 Terraform 및 provider 이해는 여전히 필요합니다.

일반적인 프롬프트와 무엇이 다른가요?

일반적인 프롬프트는 provider capability나 도구 전제조건을 확인하지 않은 채 import steps를 제안할 수 있습니다. terraform-search-import guide는 workflow를 Terraform Search support에 맞춰 고정하므로, 결과가 더 실행 가능하고 나중에 실패할 가능성도 낮아집니다.

terraform-search-import skill 개선 방법

결과를 바꾸는 입력을 제대로 주기

가장 좋은 결과는 provider, 정확한 resource type, environment scope, 그리고 discovery인지 import인지 둘 다인지까지 알려줄 때 나옵니다. 예를 들어, “subscription dev에서 지원되는 모든 azurerm_storage_account resources를 찾아 bulk import instructions를 준비해줘”는 “내 cloud resources를 import해줘”보다 훨씬 낫습니다.

흔한 실패 모드를 주의하기

가장 큰 실패는 지원되지 않는 resource에 terraform-search-import를 쓰려는 경우입니다. support check가 아무것도 반환하지 않으면, search-based solution을 억지로 만들려 하지 말고 references/MANUAL-IMPORT.md를 사용하세요. 이렇게 하면 시간을 아끼고, workflow를 provider의 실제 capability에 맞게 유지할 수 있습니다.

discovery에서 import로 단계적으로 진행하기

좋은 workflow는 다음 순서입니다: 지원 여부 확인, resource 목록 확인, 좁은 scope 선택, 그리고 첫 번째 resource가 올바른지 확인한 뒤 전체 집합으로 확장. 이 순서는 bulk import로 인해 state가 불필요하게 복잡해지기 전에 naming mismatch, 권한 누락, region 또는 account drift를 잡아내는 데 도움이 됩니다.

실제 inventory 정보로 프롬프트를 개선하기

이미 예시 resource name, ARN, ID, account와 region 경계를 알고 있다면 꼭 포함하세요. 이런 정보는 terraform-search-import가 더 정교한 query와 더 안전한 import plan을 만들도록 도와줍니다. 특히 같은 resource type이 여러 stage에 걸쳐 존재할 수 있는 backend development 환경에서는 더욱 중요합니다.