Terraform 운영 핵심 패턴 정리

글쓴이 /
Terraform import block로 기존 리소스를 코드로 편입하는 절차 요약
요약 이미지(직접 생성). 무단 사용 금지.

이 글이 다루는 것 (운영 관점)

이미 운영 중인 인프라(수동으로 만든 VPC, IAM, RDS, Kubernetes 리소스 등)를 Terraform으로 ‘안전하게’ 편입(adopt)할 때, Terraform 1.5에서 도입된 import 블록(Import block)을 활용해 재현 가능한 절차로 만드는 방법을 정리합니다.

핵심은 “한 번 가져오고 끝”이 아니라, 가져온 직후의 드리프트(Drift) 정리, state/plan의 신뢰 회복, 팀 운영에서 재발 방지까지 포함한 운영 루틴을 만드는 것입니다.

TL;DR (바로 쓰는 결론)

  • Terraform 1.5+의 import 블록은 구성(configuration) 안에 가져오기(import) 지시를 선언해, 수동 terraform import보다 재현성을 높입니다.
  • 가져오기는 끝이 아니라 시작입니다. 첫 plan에서 나오는 변경(diff)을 “정상화”하지 못하면 이후 모든 plan이 신뢰를 잃습니다.
  • 운영 절차는 “(1) 읽기 전용 준비 → (2) import 블록으로 state 편입 → (3) plan diff 정리 → (4) import 블록 제거/정리 → (5) 정책으로 재발 방지”로 고정하세요.

배경: 왜 ‘기존 리소스 편입’이 자주 실패하는가

기존 리소스를 Terraform으로 가져올 때 흔히 실패하는 패턴은 다음과 같습니다.

  • 절차가 사람마다 다름: 어떤 리소스는 CLI로 import, 어떤 리소스는 누락, 어떤 리소스는 주소(address) 체계가 다름.
  • 첫 plan이 ‘폭발’: 가져오자마자 Terraform이 “바꾸겠다”는 항목이 너무 많이 나오고, 실제로 바꾸면 장애가 날 것 같아 멈춤.
  • state가 진실이 아님: 원격 backend/locking이 있어도, 가져오기 과정에서 순서/동시성이 깨지면 state가 흔들립니다.

Terraform 1.5의 Import block은 이 중 첫 번째(재현성) 문제를 줄여주는 도구입니다. 하지만 두 번째/세 번째는 여전히 운영 설계가 필요합니다.

공식 개념: Import block(1.5+)이 무엇을 바꾸나

Terraform은 1.5 릴리즈에서 configuration에 import 블록을 도입했습니다. 이는 “어떤 실물 리소스를 어떤 주소로 state에 연결할지”를 코드로 선언할 수 있게 해줍니다.

  • 기존 방식: 사람이 로컬에서 terraform import를 실행하고 state만 변경
  • Import block 방식: 코드에 import 대상과 주소를 선언 → plan/apply 흐름에서 가져오기를 수행

정확한 문법/동작은 Terraform 공식 문서를 기준으로 확인해야 합니다. (아래 ‘공식 참고’ 섹션 링크)

실무 절차(권장): “읽기 전용”으로 시작하는 5단계 운영 루틴

1) 준비: 원격 backend/locking과 변경 금지(Freeze) 창 확보

  • 팀이 동시에 apply하지 않도록, 최소한 해당 모듈/스택에 대해 변경 금지 시간을 확보합니다.
  • 원격 backend를 쓰는 경우 state 잠금(locking)이 실제로 동작하는지 확인합니다.
  • 가능하면 가져오기 직전에는 읽기 전용 검증(plan만 수행)으로 환경을 점검합니다.

2) 구성 작성: “리소스 블록 + import 블록”을 한 커밋으로 묶기

운영에서 중요한 원칙은 state에 주소만 붙여놓고 구성은 나중에 작성하는 흐름을 피하는 것입니다. 최소한의 리소스 블록(필수 인자 포함)과 import 블록을 같은 변경으로 묶어, 리뷰 가능한 형태로 만듭니다.

예시는 Terraform 공식 문서의 import 블록 예제를 기준으로 하세요. 여기서는 개념만 요약합니다.

// (개념 예시) import {
//   to = aws_s3_bucket.logs
//   id = "my-existing-bucket"
// }
//
// resource "aws_s3_bucket" "logs" {
//   ...
// }

3) 첫 실행: plan에서 import 작업이 포함되는지 확인

  • plan 단계에서 import가 어떤 리소스에 대해 수행될지 확인합니다.
  • apply가 필요한 흐름이라면, 적용 범위를 최소화(타겟팅 등)하되 운영 정책에 맞게 사용하세요. 타겟팅은 남용하면 전체 그래프 일관성이 깨질 수 있습니다.

4) 핵심: import 직후 plan diff를 “정상화”하는 정리 작업

가져온 뒤 첫 plan에서 변경이 잔뜩 나오면, 그 변경은 크게 세 부류입니다.

  • 구성이 누락되어 Terraform이 기본값으로 되돌리려는 변경: 운영에서 가장 위험합니다. 실제 리소스 설정을 구성에 반영해야 합니다.
  • Provider/플랫폼이 계산(computed)하는 값 차이: 문서에 따라 ignore_changes 등의 전략을 검토합니다.
  • 진짜 드리프트: 누군가 콘솔/수동으로 바꿔서 발생한 차이. 원인을 기록하고, Terraform 소스로 일원화할지 정책 결정을 합니다.

이 단계가 끝나기 전에는 “다음 리소스로 넘어가지” 않는 것을 권장합니다. plan이 신뢰를 잃으면, 그 스택은 이후 운영에서 계속 비용을 발생시킵니다.

5) 정리: import 블록 제거/유지 정책과 ‘재발 방지’ 장치

Import block은 “한 번 가져오기”를 위한 선언입니다. 가져오기가 끝났다면 다음 중 하나로 정리합니다.

  • 완료 후 제거: import 작업이 끝난 뒤 불필요한 선언을 제거하여 구성을 단순화합니다.
  • 문서화 목적 유지: 조직 정책상 “어떤 방식으로 편입했는지” 남기고 싶다면, 별도 문서/런북으로 이동시키는 방식을 고려합니다.

재발 방지는 기술보다 운영 규칙입니다. 예를 들어 “콘솔 변경 금지”, “예외 변경은 PR에 사유 기록”, “모든 변경은 plan 첨부” 같은 규칙이 있어야 drift가 반복되지 않습니다.

실패 모드 6가지와 복구 가이드 (운영자용)

  1. 가져오긴 됐는데 plan이 파괴적 변경을 제안: 구성 누락/기본값 문제인지, 실제 드리프트인지 분류부터 하세요. 즉시 apply하지 말고, 문서/리소스 실제 설정을 대조해 구성에 반영합니다.
  2. 리소스 주소(to)가 팀 컨벤션과 불일치: state 주소 변경(리팩터)에는 비용이 큽니다. import 전에 주소 체계를 먼저 확정하고 리뷰를 통과시키세요.
  3. 동시 실행으로 state 충돌: 원격 잠금이 제대로 잡히는지 확인하고, 운영 시간대/권한/CI 실행 정책을 재점검합니다.
  4. Provider가 특정 속성을 매번 바꾸려 함: Provider 문서에서 해당 속성이 computed인지, ForceNew인지, ignore 가능한지 확인합니다.
  5. 환경별 차이(워크스페이스/var/locals)로 import 대상이 바뀜: import 블록이 환경을 잘못 가리키면 잘못된 리소스를 연결할 수 있습니다. 실행 전 변수/워크스페이스 확인을 체크리스트에 넣으세요.
  6. 가져온 뒤 누군가 다시 콘솔 수정: drift 감지(주기적 plan)와 변경 통제(권한/프로세스)가 없으면 반복됩니다. 기술적 해결보다 운영 통제가 먼저입니다.

실무 체크리스트 (그대로 복사해서 런북에 붙이기)

  • 변경 금지(Freeze) 창 확보: 예/아니오
  • 원격 backend/locking 확인: 예/아니오
  • import 대상 리소스 ID 2인 검증(교차 확인): 예/아니오
  • 주소(to) 컨벤션 리뷰 승인: 예/아니오
  • import 직후 plan diff 0 또는 ‘의도된 변경만 남음’: 예/아니오
  • 드리프트 원인/예외 기록(티켓/PR 링크): 예/아니오
  • 재발 방지 규칙(콘솔 변경 통제/권한): 예/아니오

FAQ

Q1. Import block을 쓰면 기존 terraform import는 필요 없나요?

Import block은 “가져오기 작업을 코드로 선언”하는 방식입니다. 조직의 워크플로우/CI 정책에 따라 어느 방식이 적합한지 달라질 수 있으니, Terraform 공식 문서의 import block 동작 설명을 기준으로 선택하세요.

Q2. 가져온 뒤 plan이 바꾸겠다는 걸 전부 막으면(무시하면) 되나요?

무조건 막으면 장기적으로 기술 부채가 됩니다. 무엇이 ‘의도된 설정’이고 무엇이 ‘드리프트’인지부터 분류해야 하며, Provider/플랫폼 공식 문서에 근거해 ignore 전략을 최소화하는 것이 안전합니다.

Q3. Kubernetes 리소스도 같은 방식으로 편입할 수 있나요?

가능/불가능은 사용 중인 Provider가 import를 어떻게 지원하는지에 달려 있습니다. Kubernetes Provider(또는 해당 도구)의 공식 문서에서 import 지원 범위와 ID 형식을 확인하세요.

공식 참고(원문)

마무리

기존 인프라를 Terraform으로 편입하는 작업은 “도구 기능”보다 “운영 절차”가 승패를 가릅니다. Import block은 재현성과 리뷰 가능성을 크게 올려주지만, import 이후 plan diff 정상화와 변경 통제가 없으면 다시 drift 지옥으로 돌아갑니다.

위로 스크롤
WordPress Appliance - Powered by TurnKey Linux