기존 인프라를 Terraform으로 이관하는 방법 - Import부터 운영 전환까지

안녕하세요 클래스메소드의 이수재입니다.

AWS 콘솔이나 다른 도구로 이미 만들어진 리소스를 Terraform으로 관리하고 싶은데,
처음부터 다시 만들자니 서비스 중단이 걱정되고, 그냥 두자니 인프라 코드와 실제 상태가 따로 노는 상황이 되어버립니다.

이런 상황에서 사용할 수 있는 것이 Terraform Import입니다.
이 글에서는 Terraform Import의 개념과 한계, 그리고 실제 사용 방법까지 알아보겠습니다.

Terraform Import란?

Terraform Import는 Terraform 외부에서 생성된 기존 인프라 리소스를 Terraform의 State(상태 파일) 에 등록하는 기능입니다.

Terraform은 리소스의 현재 상태를 terraform.tfstate 파일로 관리합니다.
Import를 사용하면 콘솔에서 직접 만든 EC2 인스턴스나 S3 버킷 같은 리소스를 이 State에 등록할 수 있고,
이후부터는 Terraform 코드로 해당 리소스를 관리할 수 있게 됩니다.

한계점

Terraform Import가 만능은 아닙니다. 실제 사용 시 몇 가지 주의해야 할 한계가 있습니다.

1. 리소스 구성 코드를 직접 작성해야 한다 (v1.5 미만)

Import 명령어는 State에 리소스를 등록할 뿐, .tf 파일(구성 코드)을 자동으로 생성해주지 않습니다.
Import 전에 실제 리소스와 일치하는 구성 코드를 직접 작성해야 합니다.
코드가 없거나 실제 상태와 다르면 Import 후 terraform plan 시 불필요한 변경이 발생합니다.

2. 모든 리소스가 Import를 지원하지 않는다

일부 리소스는 Import를 지원하지 않습니다.
사용 전 Terraform 공식 문서에서 해당 리소스의 Import 지원 여부를 확인해야 합니다.

3. 속성 값이 누락되거나 다를 수 있다

Import 후 State에 등록된 값이 실제 리소스의 모든 속성을 완벽하게 반영하지 않는 경우가 있습니다.
특히 tags, lifecycle, 계산된 속성(computed attributes) 등은 차이가 생길 수 있습니다.

사용 방법

Terraform Import에는 두 가지 방법이 있습니다.
CLI 방식 (모든 버전) 과 Import 블록 방식 (v1.5에서 추가) 입니다.

CLI 방식 (terraform import)

가장 기본적인 방법으로, 명령어를 직접 실행합니다.

terraform import <리소스 타입>.<리소스 이름> <리소스 ID>

예를 들어 EC2 인스턴스를 Import하는 경우:

terraform import aws_instance.my_server i-1234567890abcdef0

이 명령어를 실행하기 전에 .tf 파일에 리소스 블록이 미리 정의되어 있어야 합니다.

resource "aws_instance" "my_server" {
  # 실제 리소스와 일치하도록 속성 작성 필요
}

Import 블록 방식 (v1.5 이상)

Terraform 1.5부터는 .tf 파일 내에 import 블록을 선언하는 방식이 추가되었습니다.
CLI 명령어 없이도 terraform apply 시 Import가 함께 수행됩니다.

참고: https://developer.hashicorp.com/terraform/language/import

import {
  to = aws_instance.my_server
  id = "i-1234567890abcdef0"
}

resource "aws_instance" "my_server" {
  # 속성 작성
}

또한 --generate-config-out 옵션으로 구성 코드를 자동 생성할 수 있습니다.
Terraform 1.5에서 실험적(experimental)으로 도입되었고, 1.6에서 정식 지원됩니다.

참고: https://developer.hashicorp.com/terraform/language/import/generating-configuration

terraform plan -generate-config-out=generated.tf

import 블록만 작성해두면 Terraform이 실제 리소스를 읽어 .tf 코드를 자동으로 생성해줍니다.
수동으로 구성 코드를 작성해야 했던 기존 방식의 가장 큰 불편함을 해소해주는 기능입니다.

Terraformer를 이용한 일괄 Import

리소스가 수십~수백 개라면 하나씩 Import하는 것은 현실적이지 않습니다.
이런 경우에 사용할 수 있는 것이 Terraformer입니다.

Terraformer는 Google이 오픈소스로 공개한 CLI 도구로, 기존 클라우드 리소스를 스캔하여 Terraform 구성 코드와 State 파일을 자동으로 생성해줍니다.

설치

설치 방법은 버전마다 달라질 수 있으므로 공식 README를 참고하세요.
https://github.com/GoogleCloudPlatform/terraformer#installation

AWS Provider를 사용하려면 플러그인도 함께 설치해야 합니다.

# terraform 초기화 (aws provider 포함)
terraform init

사용 예시

Terraformer에서 사용하는 리소스명은 Terraform provider의 리소스 타입명과 다릅니다.
사용 가능한 리소스명 목록은 공식 문서를 확인하세요.
https://github.com/GoogleCloudPlatform/terraformer/blob/master/docs/aws.md

AWS의 EC2 인스턴스 전체를 Import하는 경우 (instance가 Terraformer에서의 EC2 리소스명):

terraformer import aws --resources=instance --regions=ap-northeast-1

여러 리소스를 한번에 Import하는 경우:

terraformer import aws --resources=instance,s3,rds --regions=ap-northeast-1

실행 후 generated/aws/ 디렉토리에 리소스별로 .tf 파일과 terraform.tfstate가 생성됩니다.

Terraformer의 한계

자동화 도구인 만큼 편리하지만, 그대로 프로덕션에 적용하기엔 정리가 필요합니다.

• 생성된 코드에 하드코딩된 값이 많아 변수화 작업 필요
• 리소스 간 참조가 ID 값으로 고정되어 있어 data source나 resource reference로 교체 필요
• 지원하지 않는 리소스가 일부 존재
  • 각 서비스 별로 지원하는 리소스가 기재되어 있습니다.
  • https://github.com/GoogleCloudPlatform/terraformer/blob/master/docs/aws.md
• 생성된 State와 실제 환경 간 미세한 차이가 있을 수 있어 terraform plan 검증 필수

기존 인프라를 Terraform으로 이관하는 실전 플로우

지금까지 소개한 내용을 바탕으로, 실제 이관 작업의 전체 흐름을 정리합니다.

전체 플로우

1. 현황 파악 → 2. 이관 범위 결정 → 3. 코드 생성 → 4. 검증 → 5. 정리 → 6. 운영 전환

1단계: 현황 파악

이관 전에 현재 인프라 상태를 파악합니다.

• 어떤 리소스가 얼마나 있는지 AWS 콘솔 또는 CLI로 확인
• 리소스 간 의존 관계 파악 (VPC → Subnet → EC2 등)
• Terraform으로 관리되지 않는 리소스 목록 정리

2단계: 이관 범위 결정

한 번에 전체를 이관하려 하면 검증이 어렵습니다.
서비스 단위 또는 리소스 유형 단위로 범위를 나눠 순차적으로 진행하는 것을 권장합니다.

3단계: 코드 생성

목적에 따라 방법을 선택합니다.

4단계: 검증 (terraform plan)

코드와 State가 준비되면 반드시 terraform plan으로 검증합니다.

terraform plan

변경 사항이 0건 이 될 때까지 코드를 수정합니다.
변경이 남아 있다면 실제 리소스와 코드 간 차이가 있다는 의미이므로, apply 전에 반드시 해결해야 합니다.

5단계: 코드 정리

자동 생성된 코드는 실용적으로 사용하기 위해 정리가 필요합니다.

• 하드코딩된 값을 변수(variable)로 추출
• 리소스 간 참조를 ID 대신 resource reference로 교체
• 불필요한 속성(기본값과 동일한 항목) 제거
• 파일 구조 정리 (main.tf, variables.tf, outputs.tf 등)

6단계: 운영 전환

코드 정리 후 팀과 함께 아래 사항을 확인하고 운영에 적용합니다.

• Remote State 설정 (S3 + DynamoDB 등)
• .terraform.lock.hcl 및 terraform.tfstate Git 관리 정책 수립
• CI/CD 파이프라인에 terraform plan / apply 단계 추가

마무리

Terraform Import는 기존 인프라를 코드로 관리하기 시작할 때 꼭 필요한 기능입니다.
v1.5 이전에는 구성 코드를 직접 작성해야 하는 번거로움이 있었지만,
Import 블록과 자동 코드 생성 기능이 추가되면서 훨씬 실용적으로 활용할 수 있게 되었습니다.

기존 환경을 코드로 변환해주는 기능을 이용하면 100% 완전한 이전이 될 것이라 생각하고 도입을 검토하는 케이스가 많습니다.
하지만 기존 환경을 완전히 파악하고 있어야 빠진 리소스가 없는지 비교할 수 있다는 점, 모든 리소스에 기능이 대응하고 있지 않다는 점 등 단순하게 기능만 도입한다고 해서 해결되는 게 많지 않다는 것을 알 수 있습니다.
또한 코드화를 하더라도 이후에는 어떤 작업을 해야 할지 막막해지는 경우도 더러 있습니다.

다만, 인프라 관리를 위한 첫걸음으로써 IaC 환경의 도입은 필요하다고 생각하는 쪽입니다.^[1]
따라서 리소스 수가 많다면 Terraformer로 초안을 만들고, 검증과 정리를 거쳐 단계적으로 이관하는 방식을 추천합니다. 코드화된 인프라를 최적화해나가면 어느 시점부터는 최적화된 관리가 완성될 것으로 생각합니다.

다음 글에서는 코드화를 진행한 후 어떤 작업들을 하면 좋을지에 대하여 알아보겠습니다.

기존 리소스를 Terraform으로 이관하려는 분들께 도움이 되었으면 합니다.
잘못된 내용이나 피드백은 must01940 지메일로 보내주시면 확인 후 반영하겠습니다.