library

Terraform은 클라우드와 온프렘 리소스를 사람이 읽는 설정 파일로 만들고, 바꾸고, 버전 관리하는 IaC(Infrastructure as Code) 도구다. 콘솔에서 클릭해 만들던 서버·스토리지·DNS 레코드를 코드로 적어 두면 같은 파일로 같은 인프라를 다시 만들 수 있고, 설정 파일을 git 같은 버전 관리 시스템에 올려 변경 이력을 남길 수 있다.

선언형과 프로바이더

.tf 설정 파일은 HCL(HashiCorp Configuration Language)로 쓴다. 여기에는 "어떤 순서로 만들지"가 아니라 "최종적으로 무엇이 있어야 하는지"를 적는다(선언형과 명령형 프로그래밍). Terraform이 거기까지 가는 단계를 계산하고, 리소스 간 의존 관계로 그래프를 만들어 서로 독립인 리소스는 병렬로 만들거나 고친다
프로바이더(provider)는 각 플랫폼의 API에 연결하는 플러그인이다. API가 열려 있는 서비스라면 대부분 다룰 수 있고, 공개 프로바이더 수천 개가 Terraform Registry에 올라와 있다(2026 기준)

terraform {
  required_providers {
    vercel = {
      source  = "vercel/vercel"
      version = ">= 4.8"
    }
  }
}
 
# api_token을 생략하면 환경변수 VERCEL_API_TOKEN에서 읽는다
provider "vercel" {
  api_token = var.vercel_api_token
}
 
resource "vercel_project" "with_git" {
  name      = "example-project-with-git"
  framework = "nextjs"
  git_repository = {
    type = "github"
    repo = "vercel/some-repo"
  }
}

워크플로: Write → Plan → Apply

Write: 위처럼 리소스를 적는다. 여러 프로바이더를 한 설정에 섞어도 된다
Plan: terraform plan이 무엇을 create·update·destroy할지 실행 계획으로 보여 준다. 설정과 현재 상태가 이미 같으면 할 일이 없다고 보고한다
Apply: 승인하면 terraform apply가 의존 순서를 지키며 계획을 실제로 적용한다

설정을 쓴 뒤 가장 먼저 terraform init으로 작업 디렉터리를 초기화한다. 이때 프로바이더 플러그인을 내려받고 state를 둘 백엔드를 준비한다. 여러 번 돌려도 설정이나 state를 지우지 않는다.

state: 실제 리소스와 설정의 대응표

Terraform은 "설정 속 이 resource 블록이 실제 어느 객체인지"를 state에 기록한다. 기본은 로컬 파일 terraform.tfstate이고 직전 상태는 terraform.tfstate.backup에 남는다. 공식 문서는 팀으로 쓸 때 state 잠금(locking)과 접근 제어를 지원하는 원격 백엔드나 HCP Terraform에 두라고 권한다. 잠금이 없으면 두 사람이 동시에 Terraform을 돌려 state가 깨질 수 있고, 로컬 state는 평문 파일이라 설정에 적은 비밀값이 그대로 들어가므로 git에 올리면 새어 나간다. 이 파일을 잃어버리면 설정과 실제 객체의 대응도 함께 사라진다. 공식 문서는 state 없이는 Terraform이 동작할 수 없다고 한다.

import: 이미 만든 리소스 끌어오기

대시보드로 먼저 만든 리소스는 state에 없으므로 Terraform이 관리하지 못한다. terraform import 명령은 실제 객체를 state에 묶어 주지만 설정은 만들어 주지 않아서, resource 블록을 먼저 손으로 써 둬야 한다.

terraform import vercel_project.example prj_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

설정까지 생성하려면 import 블록을 쓰고 terraform plan에 -generate-config-out 옵션을 주면 resource 블록을 만들어 준다. 원격 객체 하나는 resource 주소 하나에만 묶여야 한다. 같은 객체를 두 블록이 가리키면 안 된다.

Terraform

선언형과 프로바이더

워크플로: Write → Plan → Apply

state: 실제 리소스와 설정의 대응표

import: 이미 만든 리소스 끌어오기

관련 개념

연결된 개념

이 노트를 가리키는 문서

뜻이 가까운 노트