terraform import 사용법: import 블록으로 기존 리소스를 코드로 가져오기

인프라 Terraform IaC State
4 분 소요

콘솔에서 급하게 만든 S3 버킷이 있는데, 이제 테라폼으로 관리하고 싶습니다. 리소스 블록을 코드에 적고 apply 하면 될까요? 안 됩니다. 테라폼은 자기 state에 없는 리소스를 모르는 것으로 취급하므로(테라폼 기초 강좌 #5), 같은 이름의 버킷을 또 만들려다 이름 충돌로 실패합니다. 필요한 것은 “이미 있는 저 리소스가 이 코드다"라고 알려 주는 절차이고, 그것이 import입니다. 이 글은 현행 표준인 import 블록(테라폼 1.5 이상) 기준의 실전 절차입니다.

절차 요약 #

  1. import 블록을 작성합니다(대상 주소 + import ID)
  2. terraform plan -generate-config-out=generated.tf로 코드 초안을 생성합니다
  3. 초안을 다듬어 리소스 블록을 확정합니다
  4. plan이 “1 to import, 0 to change"가 될 때까지 코드를 실제에 맞춥니다
  5. apply 후 import 블록을 삭제합니다

1단계: import 블록과 ID #

import.tf 
import {
  to = aws_s3_bucket.legacy
  id = "my-console-made-bucket"
}

to는 이 리소스가 가질 테라폼 주소, id는 실제 리소스를 특정하는 식별자입니다. 여기서 가장 자주 막히는 것이 id의 형식입니다. 리소스 타입마다 다르기 때문입니다. S3 버킷은 버킷 이름, EC2 인스턴스는 인스턴스 ID(i-…), 보안 그룹 규칙처럼 복합 형식(sg-.../ingress/...)인 것도 있습니다. 추측하지 말고 provider 문서에서 해당 리소스 페이지 맨 아래의 Import 섹션을 확인하는 것이 정답입니다. 모든 리소스 문서가 자기 import ID 형식을 예시와 함께 적어 두고 있습니다.

2단계: 코드 초안 생성 #

리소스 블록을 손으로 쓰기 전에, 테라폼에게 초안을 시킵니다.

초안 생성 
terraform plan -generate-config-out=generated.tf

import 블록만 있고 대응하는 resource 블록이 없는 상태에서 이 플래그를 주면, 테라폼이 실제 리소스를 읽어 generated.tf에 리소스 블록 초안을 만들어 줍니다. 속성값을 콘솔에서 눈으로 옮겨 적는 노동이 사라집니다.

3단계: 초안 다듬기 #

생성된 코드를 그대로 쓰지 않는 이유는 두 가지입니다. 첫째, 기본값까지 전부 명시된 장황한 코드라 읽기 어렵습니다. 둘째, null이나 빈 값 인수가 섞여 있어 그대로는 validate에 걸리기도 합니다. 초안에서 의미 있는 인수만 남기고 정리해 본래 코드 파일로 옮깁니다. 팀의 기존 코드 스타일(변수 사용, 공통 태그)에 맞추는 것도 이 단계입니다.

4단계: “변경 없음"이 될 때까지 #

다듬은 코드로 plan을 실행합니다. 목표는 명확합니다.

실행 결과 
Plan: 1 to import, 0 to add, 0 to change, 0 to destroy.

여기서 0 to change가 아니라 change나 replace가 잡히면, 코드와 실제 리소스가 어긋나 있다는 뜻입니다. 그대로 apply 하면 편입과 동시에 실제 리소스가 코드 쪽 값으로 수정되므로, 의도한 변경이 아니라면 plan의 diff를 보고 코드를 실제 값에 맞춥니다. 특히 -/+(교체)가 잡힌 채 apply 하는 것은 편입이 아니라 재생성이 되니 반드시 멈춰야 합니다. 이 단계가 import 작업의 실질적인 핵심이며, 어긋남이 0이 되는 순간 편입 준비가 끝난 것입니다.

5단계: apply와 뒷정리 #

apply 하면 state에 리소스가 등록되고, 이후로는 여느 테라폼 리소스와 같습니다. 역할을 다한 import 블록은 삭제합니다(남겨 둬도 무해하지만 이력은 Git에 있으니 코드를 깔끔히 유지합니다).

알아 둘 것들 #

  • 옛 방식과의 차이: terraform import <주소> <ID> CLI 명령도 여전히 동작하지만, state를 즉시 바꾸는 명령이라 리뷰가 불가능하고 초안 생성도 없습니다. import 블록은 plan에서 결과를 미리 보고 PR로 리뷰할 수 있어 팀 작업의 기본값입니다.
  • 여러 리소스 편입: import 블록을 여러 개 나란히 두면 한 번의 plan·apply로 처리됩니다. 서로 참조가 있는 리소스들(버킷과 버킷 정책 등)은 함께 편입해야 “변경 없음"을 만들기 쉽습니다.
  • id에 표현식 사용: id 자리에는 변수나 표현식도 쓸 수 있어, 환경별로 다른 ID를 변수로 받는 구성도 가능합니다.
  • 편입 후 감사: 편입된 리소스가 많다면 보안·비용 스캐너를 한 번 돌려 볼 만합니다. 콘솔 시절의 설정이 팀 기준에 안 맞는 경우가 많기 때문입니다. 드리프트 감지와 운영 절차의 맥락은 테라폼 운영 강좌 #2에서 다뤘습니다.

정리 #

  • 기존 리소스는 apply로 못 가져옵니다. import 블록으로 “이 리소스가 이 코드다"를 선언하는 절차가 필요합니다
  • import ID 형식은 리소스마다 다릅니다. provider 문서의 Import 섹션이 정답지입니다
  • 리소스 블록은 손으로 쓰지 말고 -generate-config-out 초안을 다듬습니다
  • 완료 기준은 “1 to import, 0 to change"입니다. change가 남은 채 apply 하면 편입과 동시에 실제 리소스가 수정됩니다
  • CLI 명령 방식보다 import 블록이 리뷰 가능해 팀 기본값입니다. 편입 후에는 import 블록을 지웁니다
X