표준 모듈 구조

표준 모듈 구조 (Standard Module Structure)

재사용 가능한 Terraform 모듈에 권장되는 표준 디렉터리·파일 구조를 설명해 드릴게요. 이 구조를 따르면 모듈이 명확하고 협업하기 쉬워져요.

출처: 문서

본문

모듈 저장소는 다음 표준 구조를 따르는 것이 좋아요. 이 구조는 Terraform Registry에 게시되는 모든 모듈의 관례이며, 가독성과 유지보수성을 높여요.

표준 파일 (Standard files)

권장되는 모듈 구조:

.
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf
├── examples/
│   └── complete/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
└── LICENSE

README.md — 모듈의 용도, 사용법, 입력·출력을 설명하는 문서. 반드시 포함.
main.tf — 모듈의 리소스와 데이터 소스를 정의하는 기본 구성 파일.
variables.tf — 모듈의 입력 변수 선언.
outputs.tf — 모듈의 출력 값 선언.
examples/ — 모듈 사용 예시를 담은 디렉터리. 각 예시는 자체 루트 모듈처럼 구성됨. Registry가 예시를 자동으로 보여줘요.
LICENSE — 모듈의 라이선스. 공개 게시 시 필요.

로컬 모듈 규칙 (Local module convention)

로컬 terraform.tfstate 파일이나 .terraform/ 디렉터리, terraform.tfvars 등과 같은 인스턴스별 파일은 모듈 저장소에 포함하지 않아요. 모듈은 재사용 가능한 순수 구성이어야 해요.

파일 목적 (Purpose of each file)

main.tf: resource, data 블록과 필요한 프로바이더 설정.
variables.tf: 입력 변수를 type과 description과 함께 선언.
outputs.tf: 호출자가 사용할 출력을 description과 함께 선언.
README.md: 문서 — 필수적이며 모듈 사용에 대한 첫 정보원.

프로바이더와 의존성 (Providers and dependencies)

모듈이 사용하는 프로바이더는 모듈 안에 terraform 블록의 required_providers로 선언할 수 있어요. 프로바이더 구성 자체는 모듈에 넣지 않고 호출자가 제공하게 해요. 자세한 내용은 모듈 안의 프로바이더를 참고해요.

예시 (Examples) 디렉터리

examples/ 안의 각 하위 디렉터리는 독립적인 샘플 루트 모듈로, 모듈을 어떻게 호출·사용하는지 보여줘요:

examples/
├── complete/
│   ├── main.tf
│   ├── variables.tf
│   └── outputs.tf
└── basic/
    ├── main.tf
    ├── variables.tf
    └── outputs.tf

각 예시는 모듈을 ./../ 소스로 참조하거나 호출하지 않고, 모듈 루트에 직접 리소스를 넣을 수도 있어요. 예시는 이 모듈의 실제 사용법을 표현해요.

표준 모듈 구조