[Terraform 운영] Day 2: Module 설계 - 복사 대신 안정된 계약 만들기
이 글은 AI(Claude)의 도움을 받아 작성하고, 작성자가 검토·편집했습니다.
서론: 오늘의 문제
좋은 Terraform module은 리소스를 숨기는 상자가 아니라 조직의 인프라 결정을 재사용 가능한 계약으로 표현한다. 입력, 출력, 버전과 책임 범위를 작게 유지한다.
1. 추상화의 단위
provider 리소스 한 개를 그대로 감싼 module은 가치가 작다. 네트워크가 포함된 서비스 실행 환경처럼 함께 변경되고 같은 정책을 가져야 하는 자원 집합을 도메인 단위로 묶는다.
2. 입력 최소화
모든 provider 속성을 variable로 노출하면 module이 복잡한 전달 계층이 된다. 조직 표준은 기본값과 validation으로 고정하고 실제로 달라져야 하는 선택만 입력으로 받는다.
3. 출력 계약
호출자가 다음 구성에 필요한 안정된 식별자만 output으로 제공한다. 내부 리소스 전체를 노출하면 module 리팩터링이 모든 소비자 변경으로 번진다.
4. 버전과 Source 고정
registry module은 호환 가능한 버전 범위를 명시하고 Git source는 변경 가능한 branch보다 tag나 commit을 사용한다. 의존성 업그레이드는 plan과 소비자 테스트를 거친다.
5. 문서와 예제
변수 목록만으로는 운영 의도를 설명할 수 없다. 대표 사용 예제, 생성되는 자원, 비용과 보안 가정, 파괴적 변경의 이관 절차를 함께 제공한다.
6. 자주 실패하는 방식
거대한 범용 module은 조건문과 예외가 늘어 변경 영향 범위를 알기 어렵다. source 버전을 고정하지 않으면 같은 커밋이 실행 시점에 따라 다른 인프라를 만들 수 있다.
7. 관측과 검증
module 소비자 수, 주요 버전별 사용 분포, plan 실패, deprecated 입력 사용, 업그레이드 소요 시간과 예외 옵션 수를 관리한다. 기준값은 정상 시간대와 변경 전후를 비교해 정하고, 점검 결과가 실제 행동으로 이어지는지 정기적으로 확인한다.
실행 흐름
1
2
3
4
5
6
7
8
9
1. 추상화의 단위
↓
2. 입력 최소화
↓
3. 출력 계약
↓
4. 버전과 Source 고정
↓
5. 문서와 예제
개별 도구보다 이 순서를 팀의 설계 리뷰와 Runbook에 남기는 것이 중요하다. 상황이 달라져도 판단 근거와 검증 결과가 이어져야 한다.
실전 체크리스트
- 추상화의 단위: 기준과 책임자를 문서화했다.
- 입력 최소화: 기준과 책임자를 문서화했다.
- 출력 계약: 기준과 책임자를 문서화했다.
- 버전과 Source 고정: 기준과 책임자를 문서화했다.
- 문서와 예제: 기준과 책임자를 문서화했다.
- 실패 패턴을 재현하고 안전한 복구 경로를 확인했다.
- 핵심 신호를 대시보드와 변경 검증에 연결했다.
참고 자료
다음 글
다음 글에서는 Plan과 Apply - 검토한 변경만 실행하기를 다룬다.