Terraform을 팀에서 사용하는 방법

소개

Terraform은 강력한 Infrastructure as Code(IaC) 도구이지만, 팀 단위에서는 체계적인 관리가 필요합니다. 이 글에서는 팀에서 Terraform을 효과적으로 활용하는 방법에 대해 알아보겠습니다.

목차

1. 코드형 인프라(IaC) 도입
2. 애플리케이션 코드 vs 인프라 코드 워크플로우
3. 팀 단위 Terraform 관리 전략
4. Atlantis를 활용한 자동화
5. 실전 적용 가이드

1. 코드형 인프라(IaC) 도입

버전 관리의 중요성

모든 인프라 코드는 버전 관리 시스템에서 관리되어야 합니다:

• Terraform 설정 파일
• 문서(README.md)
• 환경 설정 파일
• 테스트 코드
• 데이터베이스 스키마

저장소 구조

infrastructure/
├── modules/              # 재사용 가능한 모듈
│   ├── networking/
│   ├── database/
│   └── compute/
└── live/                 # 실제 환경 설정
    ├── prod/
    ├── staging/
    └── dev/

테라폼 황금률

"메인 브랜치는 항상 프로덕션 환경과 1:1로 매칭되어야 한다"

 

이는 다음을 의미합니다:

• 수동 변경 금지
• 상태 파일의 정확한 관리
• 모든 변경사항은 코드로 관리

2. 애플리케이션 코드 vs 인프라 코드 워크플로우

공통점

1. 버전 관리 사용
2. 코드 리뷰 프로세스
3. 자동화된 테스트
4. CI/CD 파이프라인

차이점

구분	애플리케이션 코드	인프라 코드
테스트 환경	로컬 가능	실제 환경 필요
롤백	쉬움	복잡하거나 불가능
배포 전략	다양한 옵션	제한적
승인 프로세스	자동화 가능	수동 검토 필요

3. 팀 단위 Terraform 관리 전략

모듈화 전략

# 재사용 가능한 모듈 예시
module "vpc" {
  source = "../../modules/networking/vpc"

  environment = var.environment
  cidr_block  = var.vpc_cidr

  tags = {
    Environment = var.environment
    Managed_by  = "terraform"
  }
}

환경 분리

# 환경별 설정 예시
terraform {
  backend "s3" {
    bucket = "company-terraform-state"
    key    = "env/${var.environment}/network/terraform.tfstate"
    region = "us-west-2"
  }
}

팀 협업 규칙

1. 코드 리뷰 필수
2. 테스트 자동화
3. 문서화 표준
4. 명명 규칙 준수

4. Atlantis를 활용한 자동화

참고 : https://okms1017.tistory.com/70

Atlantis는 Terraform 워크플로우를 GitHub과 통합하여 자동화하는 강력한 도구입니다. 이 가이드에서는 GitHub 저장소와 Atlantis를 연동하는 전체 과정을 상세히 설명하겠습니다.

1. 사전 준비사항

필수 요구사항

• GitHub 계정 및 저장소
• Terraform 코드가 있는 GitHub 저장소
• Atlantis를 실행할 서버 (EC2, Docker 등)
• GitHub Personal Access Token

GitHub Token 생성

1. GitHub 설정 → Developer settings → Personal access tokens → Tokens (classic)
2. "Generate new token" 클릭
3. 필요한 권한 선택:
   • repo (전체)
   • admin:repo_hook
   • admin:org_hook

# 토큰을 안전한 곳에 저장
export GITHUB_TOKEN="ghp_your_token_here"

2. GitHub 설정

저장소 준비

# 테스트용 저장소 생성
git clone https://github.com/your-org/terraform-repo.git
cd terraform-repo

# Atlantis 설정 파일 생성
touch atlantis.yaml

atlantis.yaml 기본 설정

version: 3
projects:
- name: terraform-project
  dir: .
  workspace: default
  terraform_version: v1.0.0
  delete_source_branch_on_merge: true
  autoplan:
    when_modified: ["*.tf", "../modules/**/*.tf"]
    enabled: true
  apply_requirements: ["approved", "mergeable"]
  workflow: default

Webhook 설정

1. 저장소 Settings → Webhooks → Add webhook
2. Payload URL: https://your-atlantis-server/events
3. Content type: application/json
4. Secret: your-webhook-secret
5. Events: Pull requests, Pushes 선택

3. Atlantis 서버 설정

Docker를 이용한 설치

docker run \
  --name atlantis \
  -p 4141:4141 \
  -v /path/to/atlantis/data:/data \
  ghcr.io/runatlantis/atlantis:latest \
  server \
  --atlantis-url="https://your-atlantis-server" \
  --gh-user="your-github-username" \
  --gh-token="$GITHUB_TOKEN" \
  --gh-webhook-secret="your-webhook-secret" \
  --repo-allowlist="github.com/your-org/*"

SSL 설정 (필수)

# Nginx 설정 예시
server {
    listen 443 ssl;
    server_name your-atlantis-server;

    ssl_certificate /etc/letsencrypt/live/your-atlantis-server/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-atlantis-server/privkey.pem;

    location / {
        proxy_pass http://localhost:4141;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

4. 저장소 구성

프로젝트 구조

terraform-repo/
├── atlantis.yaml
├── terraform/
│   ├── main.tf
│   ├── variables.tf
│   └── outputs.tf
└── modules/
    └── example/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

상세 Atlantis 설정

# atlantis.yaml
version: 3
automerge: true
projects:
- name: infrastructure
  dir: terraform
  workspace: default
  terraform_version: v1.0.0
  delete_source_branch_on_merge: true
  autoplan:
    when_modified: ["*.tf", "../modules/**/*.tf"]
    enabled: true
  apply_requirements: ["approved"]
  workflow: custom
workflows:
  custom:
    plan:
      steps:
      - init:
          extra_args: ["-upgrade"]
      - plan:
          extra_args: ["-lock=false"]
    apply:
      steps:
      - apply

5. 워크플로우 테스트

테스트 PR 생성

# 새 브랜치 생성
git checkout -b feature/test-atlantis

# Terraform 파일 수정
echo 'resource "null_resource" "example" {}' >> terraform/main.tf

# 변경사항 커밋 및 푸시
git add terraform/main.tf
git commit -m "test: Add null resource for Atlantis testing"
git push origin feature/test-atlantis

Atlantis 명령어

PR 코멘트에서 사용할 수 있는 명령어:

• atlantis plan - 수동으로 plan 실행
• atlantis apply - 변경사항 적용
• atlantis help - 도움말 표시

6. 고급 설정

사용자 정의 워크플로우

# custom_workflow.yaml
workflows:
  production:
    plan:
      steps:
      - env:
          name: AWS_REGION
          value: us-west-2
      - init
      - plan:
          extra_args: ["-var-file=production.tfvars"]

승인 정책 설정

apply_requirements:
  - approved
  - mergeable
  - undiverged

환경 변수 설정

docker run \
  -e "AWS_ACCESS_KEY_ID=your-access-key" \
  -e "AWS_SECRET_ACCESS_KEY=your-secret-key" \
  -e "AWS_REGION=us-west-2" \
  ... # 기존 Atlantis 설정

7. 문제 해결

일반적인 문제

1. Webhook 연결 실패
   • SSL 인증서 확인
   • 방화벽 설정 검토
   • Webhook 시크릿 확인
2. Plan 실패
   • bash

     // Atlantis 로그 확인
     docker logs atlantis
     // Webhook 이벤트 테스트
     curl -X POST https://your-atlantis-server/events \
     -H "Content-Type: application/json" \
     -d @webhook-test-payload.json

3. 권한 문제
   • yaml

     // IAM 정책 예시
     {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "terraform:*",
            "ec2:*"
          ],
          "Resource": "*"
        }
      ]
     }

결론

GitHub과 Atlantis의 연동을 통해 다음과 같은 이점을 얻을 수 있습니다:

• 자동화된 Terraform 워크플로우
• 코드 리뷰와 통합된 인프라 변경
• 안전한 승인 프로세스
• 변경사항 추적 및 감사

유용한 팁

• 항상 terraform plan 결과를 검토
• 중요한 변경사항은 여러 리뷰어가 확인
• 정기적으로 Atlantis 로그 모니터링
• 주기적인 백업 설정

참고 자료

• Atlantis 공식 문서
• GitHub Webhook 가이드
• Terraform 모범 사례