Terraform 사용 가이드
이 문서는 Terraform의 기본 개념부터 프로바이더 설정과 카카오클라우드 리소스 관리 방법까지 안내합니다.
Terraform 기본 개념
Terraform은 인프라를 코드로 정의하고 관리하는 Infrastructure as Code (IaC) 도구입니다. 필요한 리소스와 원하는 설정을 구성 파일에 작성하면, Terraform이 현재 상태와 비교하여 변경 계획을 만들고 적용합니다.
구성 파일은 버전 관리 시스템에서 변경 이력을 추적하고 팀원과 함께 검토할 수 있습니다. 반복해서 사용하는 구성을 모듈로 묶으면 개발·검증·운영 환경에 공통 구성을 재사용할 수 있습니다. Terraform의 기본 동작은 HashiCorp Terraform 소개를 참고하세요.
Terraform 구성에서 사용하는 주요 개념은 다음과 같습니다.
| 개념 | 설명 |
|---|---|
| 프로바이더(Provider) | Terraform과 외부 서비스의 API를 연결하는 플러그인 |
| 리소스(Resource) | Terraform으로 생성·변경·삭제할 인프라 객체 - 구성 파일의 resource 블록으로 정의 |
| 데이터 소스(Data source) | 기존 리소스 등의 정보를 조회하여 구성에 활용하는 방법 - data 블록으로 정의하며, 조회 대상 자체를 생성하거나 변경하지 않음 |
| 상태(State) | 구성 파일의 리소스와 실제 인프라 객체의 연결 정보를 기록하는 데이터 |
| 실행 계획(Plan) | 구성과 현재 인프라를 비교하여 적용할 생성·변경·삭제 작업을 보여 주는 결과 |
KakaoCloud Terraform Provider
KakaoCloud Terraform Provider는 Terraform과 카카오클라우드 API를 연결하는 플러그인입니다. 이를 사용하면 Terraform 구성 파일로 카카오클라우드의 컴퓨팅·네트워크·데이터베이스·Kubernetes 등의 리소스를 관리할 수 있습니다.
지원하는 리소스와 데이터 소스는 프로바이더 버전에 따라 다릅니다. 사용할 버전을 선택한 후 Terraform Registry에서 해당 항목의 필수 인자와 예제를 확인하세요.
사용 준비
Terraform과 프로바이더를 사용하려면 다음을 준비해야 합니다.
| 구분 | 준비 항목 |
|---|---|
| Terraform | Terraform CLI 1.14 이상 |
| 프로바이더 | 카카오클라우드 인증에 사용할 애플리케이션 자격 증명 ID와 시크릿 |
| 카카오클라우드 프로젝트 | 관리할 프로젝트와 리소스에 대한 권한 |
자격 증명 발급 방법은 자격 증명 관리를 참고하세요.
프로바이더 설정
작업 디렉터리의 main.tf 파일에 프로바이더 소스와 사용할 버전을 지정합니다. 다음 예제는 0.4.5 버전을 사용하며, 인증 정보는 환경 변수로 전달합니다.
terraform {
required_version = ">= 1.14.0"
required_providers {
kakaocloud = {
source = "kakaoenterprise/kakaocloud"
version = "0.4.5"
}
}
}
provider "kakaocloud" {}
인증 방식
프로바이더는 provider 블록에 지정한 인증 인자를 먼저 확인하고, 환경 변수의 인증 정보를 확인합니다. 각 값에 대응하는 인자와 환경 변수는 다음과 같습니다.
| 인증 정보 | 프로바이더 인자 | 환경 변수 |
|---|---|---|
| 애플리케이션 자격 증명 ID | application_credential_id | KAKAOCLOUD_APPLICATION_CREDENTIAL_ID |
| 애플리케이션 자격 증명 시크릿 | application_credential_secret | KAKAOCLOUD_APPLICATION_CREDENTIAL_SECRET |
환경 변수를 사용하는 경우 Terraform을 실행할 터미널에서 다음 값을 설정합니다. 예제의 값을 발급받은 자격 증명으로 바꾸세요.
export KAKAOCLOUD_APPLICATION_CREDENTIAL_ID="<APPLICATION_CREDENTIAL_ID>"
export KAKAOCLOUD_APPLICATION_CREDENTIAL_SECRET="<APPLICATION_CREDENTIAL_SECRET>"
프로바이더 인자를 사용하려면 앞의 빈 provider 블록을 다음과 같이 변경하고 입력 변수를 선언합니다. 실행할 때 변수 값을 전달하세요.
variable "application_credential_id" {
type = string
sensitive = true
}
variable "application_credential_secret" {
type = string
sensitive = true
}
provider "kakaocloud" {
application_credential_id = var.application_credential_id
application_credential_secret = var.application_credential_secret
}
실제 인증 정보가 포함된 구성 파일이나 변수 파일은 소스 코드 저장소에 커밋하지 마세요.
인증 방식의 상세 설명은 KakaoCloud Terraform Provider 공식 문서를 참고하세요.
기본 사용 흐름
프로바이더와 인증 정보를 설정한 후, 관리할 리소스의 구성까지 작성해야 인프라를 생성할 수 있습니다. 앞의 프로바이더 설정만으로는 리소스가 생성되지 않습니다.
| 단계 | 작업 | 설명 |
|---|---|---|
| 1. 구성 작성 | .tf 파일 작성 | 공식 문서의 예제를 참고하여 리소스와 필요한 인자를 정의 |
| 2. 초기화 | terraform init | 작업 디렉터리를 초기화하고 필요한 프로바이더를 설치 |
| 3. 구성 검증 | terraform validate | 구성의 구문과 내부 일관성을 검사. 실제 API 접근 권한이나 생성 가능 여부를 보장하지는 않음 |
| 4. 계획 확인 | terraform plan | 생성·변경·삭제할 리소스와 속성을 검토 |
| 5. 적용 | terraform apply | 실행 계획을 확인하고 승인하여 실제 인프라에 변경 사항을 반영 |
리소스를 변경할 때도 구성 파일을 수정한 후 계획을 확인하고 적용합니다. 일부 속성 변경은 리소스 교체로 이어질 수 있으므로, 적용 전에 삭제·재생성 항목을 확인하세요.
상태 관리
Terraform은 상태 정보를 사용해 구성의 리소스와 실제 인프라 객체를 연결합니다. 기본적으로 상태는 작업 디렉터리의 terraform.tfstate 파일에 저장됩니다.
상태 파일에는 민감한 정보가 포함될 수 있으므로 Git 저장소에 커밋하지 마세요. 여러 사람이 같은 인프라를 관리하는 경우에는 안전한 접근 제어와 상태 잠금을 지원하는 원격 백엔드를 사용하는 것을 권장합니다.
상태 저장 방식과 백엔드별 잠금 지원 여부는 Terraform 상태 관리를 참고하세요.
관련 문서
- KakaoCloud Terraform Provider 공식 문서 ↗: 버전별 프로바이더 설정, 리소스와 데이터 소스의 인자 및 예제
- KakaoCloud Terraform Provider 소스 코드 ↗: 구현 코드와 변경 사항
Terraform 튜토리얼
- Terraform으로 VM 프로비저닝 및 변경: 기존 서브넷에 VM을 생성하고 Terraform으로 리소스를 변경·삭제하는 기본 실습
- Terraform으로 MySQL 기반 3-Tier 웹 서비스 구축: Terraform으로 카카오클라우드 리소스를 구성하고 3-Tier 웹 서비스 배포