terraform init 명령

terraform init 명령은 Terraform 구성 파일이 들어 있는 작업 디렉터리를 초기화하는 명령이에요. 새 Terraform 구성을 작성하거나 버전 관리에서 기존 구성을 복제(clone)한 뒤 가장 먼저 실행해야 하는 명령이에요. 이 명령은 여러 번 실행해도 안전해요.

출처: 문서

본문

Hands-on: Terraform: Get Started 튜토리얼을 시도해 보세요. init 명령에 대한 더 자세한 내용은 Initialize Terraform Configuration 튜토리얼을 확인해 주세요.

사용법 (Usage)

terraform init [options]

이 명령은 현재 작업 디렉터리를 Terraform에서 사용할 수 있도록 준비하기 위해 여러 초기화 단계를 수행해요. 각 단계에 대한 자세한 내용은 아래 섹션들에 있지만, 대부분의 경우 개별 단계를 걱정할 필요는 없어요.

이 명령은 구성의 변경 사항을 반영해서 작업 디렉터리를 최신 상태로 만들기 위해 여러 번 실행해도 항상 안전해요. 이후 실행에서 오류가 날 수는 있지만, 이 명령이 기존 구성이나 상태를 삭제하는 일은 절대 없어요.

일반 옵션 (General Options)

다음 옵션들은 모든(또는 여러) 초기화 단계에 적용돼요.

-input=true: 필요한 경우 입력을 요청함. false면 입력이 필요할 때 오류가 발생함.
-lock=false: 상태 관련 작업 중 상태 파일 잠금을 비활성화함.
-lock-timeout=<duration>: Terraform이 상태 잠금을 획득하기 위해 기다리는 시간을 덮어씀. 기본값은 0s(0초)로, 잠금이 다른 프로세스에 이미 보유되어 있으면 즉시 실패함.
-no-color: 명령 출력의 색상 코드를 비활성화함.
-upgrade: 각 설치 단계에서 모듈과 플러그인을 업그레이드하도록 선택함. 자세한 내용은 아래 섹션들을 참고해 주세요.
-json: 기계가 읽을 수 있는 JSON UI 출력을 활성화함.

소스 모듈 복사 (Copy a Source Module)

기본적으로 terraform init은 작업 디렉터리에 이미 구성이 있다고 가정하고 해당 구성을 초기화하려고 시도해요.

선택적으로 -from-module=MODULE-SOURCE 옵션으로 빈 디렉터리에 대해 init을 실행할 수 있는데, 이 경우 다른 초기화 단계가 실행되기 전에 주어진 모듈이 대상 디렉터리로 복사돼요.

이 특수 모드는 두 가지 사용 사례를 지원해요.

버전 관리 소스를 사용할 때, 버전 관리에서 구성을 체크아웃한 다음 작업 디렉터리를 초기화하는 짧은 방법으로 사용할 수 있어요.
소스가 예제 구성을 참조한다면, 새 구성의 기반으로 사용하기 위해 로컬 디렉터리에 복사될 수 있어요.

일상적인 사용에서는 버전 관리 시스템의 자체 명령을 사용해서 구성을 별도로 체크아웃하는 것을 권장해요. 이렇게 하면 필요할 때 버전 관리 시스템에 추가 플래그를 전달할 수 있고, terraform init을 실행하기 전에 다른 준비 단계(구성 생성이나 자격 증명 활성화 등)를 수행할 수 있어요.

백엔드 초기화 (Backend Initialization)

init 중에 루트 구성 디렉터리에서 백엔드 구성을 확인하고, 주어진 구성 설정을 사용해서 선택된 백엔드를 초기화해요.

이미 초기화된 백엔드로 init을 다시 실행하면 작업 디렉터리가 새 백엔드 설정을 사용하도록 갱신돼요. 백엔드 구성을 갱신하려면 -reconfigure 또는 -migrate-state 중 하나를 제공해야 해요.

-migrate-state 옵션은 기존 상태를 새 백엔드로 복사하려고 시도하며, 변경된 내용에 따라 워크스페이스 상태 마이그레이션을 확인하는 대화형 프롬프트가 나타날 수 있어요. -force-copy 옵션은 이 프롬프트를 생략하고 마이그레이션 질문에 "yes"로 답해요. -force-copy를 활성화하면 -migrate-state 옵션도 자동으로 활성화돼요.
-reconfigure 옵션은 기존 구성을 무시해서 기존 상태의 마이그레이션을 방지해요.

백엔드 구성을 건너뛰려면 -backend=false를 사용해요. 일부 init 단계는 초기화된 백엔드가 필요하므로, 이 플래그는 작업 디렉터리가 특정 백엔드용으로 이미 초기화된 경우에만 사용하는 것이 좋아요.

-backend-config=... 옵션은 백엔드 설정이 동적이거나 민감해서 구성 파일에 정적으로 지정할 수 없는 상황에서 부분 백엔드 구성에 사용할 수 있어요.

하위 모듈 설치 (Child Module Installation)

init 중에 Terraform은 구성에서 module 블록을 검색하고, source 인자에 주어진 위치에서 참조된 모듈의 소스 코드를 가져와요.

모듈이 이미 설치된 상태에서 init을 다시 실행하면 마지막 init 이후 구성에 추가된 모듈의 소스만 설치하고, 이미 설치된 모듈은 변경하지 않아요. 이 동작을 덮어쓰려면 -upgrade를 사용해서 모든 모듈을 사용 가능한 최신 소스 코드로 갱신해요.

하위 모듈 설치를 건너뛰려면 -get=false를 사용해요. 일부 init 단계는 모듈 트리가 완전할 때만 완료될 수 있으므로, 이 플래그는 작업 디렉터리가 이미 하위 모듈로 초기화된 경우에만 사용하는 것이 좋아요.

Terraform은 대부분의 입력 변수를 플랜을 만들 때 평가하므로, init 중에는 그 값들을 사용할 수 없어요. 모듈 블록의 source 또는 version 인자에서 참조하는 입력 변수는 반드시 const = true를 선언해야 해요. 자세한 내용은 variable 블록 참조 문서를 참고해 주세요.

플러그인 설치 (Plugin Installation)

대부분의 Terraform 프로바이더는 플러그인으로 Terraform과 별개로 배포돼요. init 중에 Terraform은 구성에서 프로바이더에 대한 직접 및 간접 참조를 검색하고 해당 프로바이더의 플러그인을 설치하려고 해요.

공개 Terraform Registry나 타사 프로바이더 레지스트리에 게시된 프로바이더의 경우 terraform init이 필요한 프로바이더 플러그인을 자동으로 찾아 다운로드하고 설치해요. 원본 레지스트리에서 프로바이더를 설치할 수 없거나 설치하고 싶지 않다면, CLI 구성의 프로바이더 설치 설정을 사용해서 Terraform이 프로바이더를 설치하는 방법을 사용자 정의할 수 있어요.

각 모듈에 필요한 프로바이더를 지정하는 방법에 대한 자세한 내용은 Provider Requirements 문서를 참고해 주세요.

성공적으로 설치한 후 Terraform은 선택한 프로바이더에 대한 정보를 의존성 잠금 파일(dependency lock file)에 기록해요. 이 파일을 버전 관리 시스템에 커밋해서 나중에 terraform init을 다시 실행할 때 Terraform이 정확히 동일한 프로바이더 버전을 선택하도록 해야 해요. Terraform이 의존성 잠금 파일을 무시하고 새 버전 설치를 고려하도록 하려면 -upgrade 옵션을 사용해요.

다음 옵션으로 terraform init의 플러그인 동작을 수정할 수 있어요.

-upgrade: 이전에 선택된 모든 플러그인을 구성의 버전 제약 조건을 충족하는 최신 버전으로 업그레이드함. 이렇게 하면 Terraform이 의존성 잠금 파일에 기록된 선택을 무시하고 구성된 버전 제약 조건과 일치하는 사용 가능한 최신 버전을 선택함.
-get-plugins=false: 플러그인 설치를 건너뜀.

참고: Terraform 0.13부터 이 옵션은 provider_installation 및 plugin_cache_dir 설정으로 대체됐어요. Terraform 0.13 이상 버전에서는 이 옵션을 사용하지 말아야 하며, Terraform 0.15에서 제거됐어요.
-plugin-dir=PATH: CLI 구성에서 filesystem_mirror로 구성된 것처럼 지정한 디렉터리에서만 플러그인을 읽도록 강제함. 특정 파일시스템 미러를 정기적으로 사용하려면 Terraform의 설치 방법을 전역적으로 구성하는 것을 권장해요. -plugin-dir은 개발 중인 프로바이더 플러그인의 로컬 빌드를 테스트할 때 같은 예외적인 상황에서 일회성 재정의로 사용할 수 있어요.
-lockfile=MODE: 의존성 잠금 파일 모드를 설정함.

잠금 파일 모드의 유효한 값은 다음과 같아요.

readonly: 잠금 파일 변경을 억제하지만 이미 기록된 정보에 대해 체크섬을 검증함. -upgrade 플래그와 충돌해요. 타사 의존성 관리 도구로 잠금 파일을 갱신한다면, 언제 변경할지 명시적으로 제어하는 게 유용할 수 있어요.

자동화에서 `terraform init` 실행하기 (Running `terraform init` in automation)

변경 관리 및 배포 파이프라인의 핵심 부분으로 Terraform을 사용하는 팀이라면, 실행 간 일관성을 보장하고 버전 관리 훅과의 통합 같은 흥미로운 기능을 제공하기 위해 자동화에서 Terraform 실행을 조율하고 싶을 수 있어요.

이런 환경에서 init을 실행할 때는 반복 재설치를 피하기 위해 플러그인을 선택적으로 로컬에서 사용할 수 있게 하는 등 몇 가지 특별한 고려 사항이 있어요. 자세한 내용은 Running Terraform in Automation 튜토리얼을 참고해 주세요.

다른 구성 디렉터리 전달하기 (Passing a Different Configuration Directory)

Terraform v0.13 이하에서는 terraform apply의 플랜 파일 인자 대신 디렉터리 경로도 허용했어요. 이 경우 Terraform은 현재 작업 디렉터리 대신 해당 디렉터리를 루트 모듈로 사용했어요.

이 사용법은 Terraform v0.14에서도 여전히 지원되지만 이제 더 이상 권장되지 않으며(deprecated), Terraform v0.15에서 제거됐어요. 루트 모듈 디렉터리를 재정의하는 워크플로를 사용한다면, 모든 명령에서 동작하고 Terraform이 현재 작업 디렉터리에서 보통 읽고 쓰는 모든 파일에 대해 지정한 디렉터리를 일관되게 찾도록 하는 -chdir 전역 옵션을 사용해 주세요.

이전에 이 레거시 패턴을 사용할 때 루트 모듈 디렉터리가 재정의되었음에도 .terraform 하위 디렉터리를 현재 작업 디렉터리에 작성하는 것에 의존했다면, TF_DATA_DIR 환경 변수로 Terraform이 .terraform 디렉터리를 현재 작업 디렉터리가 아닌 다른 위치에 작성하도록 지시해 주세요.

더 알아보기 (Learn more)

terraform plan / apply 명령
백엔드 구성 문서
프로바이더 설치 설정 문서
의존성 잠금 파일(.terraform.lock.hcl) 문서

terraform init 명령