GitOps를 통한 Terraform 협업 환경 구축하기 (with Atlantis)

Intro

Terraform을 업무 환경에서 사용하면서 여러 의문점이 생겨났습니다. Terraform은 IaC(Infrastructure as Code) 도구이지만, 실제로는 '코드'로서 대하지 못하는 경우가 많았습니다. 구성원들 사이에 코드 리뷰가 부족하고, 변경 이력 관리가 어려웠으며, 초기 환경 구성 후 콘솔에서 수작업으로 변경하는 경우도 많았습니다.

이번 글에서는 Terraform 코드를 여러 구성원이 함께 효과적으로 관리할 수 있게 해주는 Atlantis를 소개하고, Kubernetes 환경에서 Helm을 사용해 배포하는 방법을 알아보겠습니다.

또한, Github Pull Request를 통한 협업 워크플로우에 대해 설명하겠습니다.

Atlantis란?

Atlantis는 Pull Request를 통해 Terraform 워크플로우를 자동화할 수 있는 오픈소스 셀프호스팅 도구입니다. 새로운 PR이 생성되면 구성원들은 서로의 Terraform 코드를 리뷰하고, PR을 승인하며, Terraform plan, apply를 수행할 수 있습니다.

모든 구성원이 자신의 로컬 환경에서 Terraform을 사용하는 것은 여러 문제를 야기합니다:

• 각 작업자에게 AWS 크레덴셜이 필요해 유출 위험이 높음
• Terraform 프로비저닝 상태를 공유하기 어려움
• 코드 리뷰 과정이 번거로움
• 상태 추적이 어려운 상황 발생 가능

Kubernetes에 Helm으로 Atlantis 배포하기

사전 준비

1. 작동하는 Kubernetes 클러스터
2. kubectl이 구성된 환경
3. Helm 설치
4. Github 계정 및 권한(access token)

Step 1. Github Token 생성

Github에서 repo 권한을 가진 토큰을 생성합니다:

1. Github 계정 Settings > Developer settings > Personal access tokens
2. 새 토큰 생성 시 repo 권한 부여
3. 생성된 토큰을 안전한 곳에 저장

Step 2. Helm Repository 추가 및 업데이트

helm repo add runatlantis https://runatlantis.github.io/helm-charts
helm repo update

Step 3. Atlantis 배포를 위한 values.yaml 파일 생성

Atlantis 배포를 위한 Helm values 파일을 생성합니다:

# atlantis-values.yaml
service:
  type: NodePort

ingress:
  enabled: false

# GitHub 인증 정보
github:
  user: "GITHUB_USERNAME"
  token: "GITHUB_TOKEN"
  secret: "WEBHOOK_SECRET"

# 허용할 조직이나 저장소 설정
orgAllowlist: "*"

# Atlantis URL 설정 (클러스터 외부에서 접근 가능한 URL)
atlantisUrl: "http://your-domain-or-ip:port"

이 파일을 atlantis-values.yaml로 저장합니다. 실제 값으로 다음을 대체해주세요:

• GITHUB_USERNAME: GitHub 사용자 이름
• GITHUB_TOKEN: 앞서 생성한 토큰
• WEBHOOK_SECRET: 웹훅에 사용할 임의의 비밀 문자열
• your-domain-or-ip:port: Atlantis에 접근 가능한 URL

Step 4. Helm으로 Atlantis 배포

helm install atlantis-deployment runatlantis/atlantis -f atlantis-values.yaml

배포 상태 확인:

kubectl get pods -l app=atlantis

서비스 확인:

kubectl get svc -l app=atlantis

Step 5. 외부 접속 설정

NodePort로 배포한 경우:

# NodePort 확인
kubectl get svc atlantis-deployment

출력된 포트 정보를 확인하고 해당 포트로 접속할 수 있도록 설정합니다.

 

 

이 정도만으로도 테스트할 수 있는 환경이 만들어졌다. 

하지만 제대로 배포를 하기 위해서는 많은 것들을 추가해 배포해야한다. 

참고했던 블로그와 github를 참조한다. 

블로그 : https://devops-art-factory.gitbook.io/devops-workshop/terraform/atlantis/atlantis-main

github : https://github.com/DevopsArtFactory/atlantis-deploy?tab=readme-ov-file  

Step 6. Github Webhook 설정

1. 배포 대상 Github 저장소의 Settings > Webhooks 탭으로 이동
2. Add webhook 버튼 클릭
3. 다음 정보 입력:
   • Payload URL: http://<ATLANTIS_URL>/events (atlantisUrl 값)
   • Content type: application/json
   • Secret: 앞서 설정한 웹훅 비밀 문자열
   • 이벤트 선택: Pull request reviews, Pushes, Issue comments, Pull requests
4. Add webhook 버튼 클릭

Github PR을 통한 Terraform 협업 워크플로우

이제 실제 팀 협업에서 Atlantis를 어떻게 활용하는지 살펴보겠습니다.

1. 개발 브랜치 생성

각 팀원은 인프라 변경 작업을 위해 개발 브랜치를 생성합니다:

git clone https://github.com/your-org/your-terraform-repo.git
cd your-terraform-repo
git checkout -b feature/add-new-ec2-instance

2. Terraform 코드 변경

개발 브랜치에서 Terraform 코드를 변경합니다:

# EC2 인스턴스 추가 예시
echo '
resource "aws_instance" "new_app_server" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
  tags = {
    Name = "AppServer"
  }
}
' >> main.tf

git add main.tf
git commit -m "Add new application server"
git push origin feature/add-new-ec2-instance

3. Pull Request 생성

Github에서 PR을 생성합니다:

1. Github 저장소 페이지에서 Compare & pull request 버튼 클릭
2. PR 제목과 설명 입력 (변경 내용과 목적 명시)
3. Create pull request 버튼 클릭

4. Atlantis 명령 실행

PR이 생성되면 코멘트 섹션에서 Atlantis 명령을 실행합니다:

atlantis plan

이 명령을 입력하면 Atlantis는 다음 작업을 수행합니다:

1. 저장소를 클론하고 해당 PR 브랜치로 체크아웃
2. terraform init 실행
3. terraform plan 실행
4. 계획 결과를 PR 코멘트에 자동으로 포스팅

5. 코드 리뷰 진행

팀원들은 PR에서:

1. 코드 변경 사항 검토
2. Atlantis가 생성한 plan 결과 검토
3. 필요시 변경 요청 (코멘트 또는 리뷰)
4. 변경 승인

6. 변경 사항 적용

코드 리뷰가 완료되고 승인되면 PR에 다음 명령을 입력합니다:

atlantis apply

Atlantis는 다음 작업을 수행합니다:

1. terraform apply 실행
2. 적용 결과를 PR 코멘트에 포스팅

7. PR 병합

모든 변경 사항이 적용되고 리뷰 요구사항이 충족되면 PR을 main 브랜치로 병합합니다.

협업 워크플로우의 이점

이 프로세스는 다음과 같은 이점이 있습니다:

1. 코드 품질 향상
   • 모든 변경 사항이 리뷰를 거침
   • 표준화된 패턴과 모범 사례 적용 가능
2. 안전한 인프라 변경
   • 자동화된 계획 단계로 의도하지 않은 변경 방지
   • 다수의 검토자가 변경 사항 검증
3. 지식 공유
   • 팀원 간 코드 리뷰를 통한 학습
   • 인프라 변경에 대한 가시성 제공
4. 감사 및 추적성
   • 모든 인프라 변경이 Git 기록에 문서화됨
   • 각 변경 사항의 이유와 설명이 PR에 기록됨
5. 중앙 집중식 자격 증명 관리
   • 개별 팀원이 자격 증명을 관리할 필요 없음
   • 보안 강화

실제 사용 사례 예시

시나리오: 새로운 마이크로서비스 인프라 추가

1. 작업 시작: 개발자 A가 feature/new-microservice-infra 브랜치 생성
2. 코드 작성:
   • VPC, 서브넷, 보안 그룹 추가
   • EKS 클러스터 구성
   • RDS 데이터베이스 설정
3. PR 생성: 상세한 설명과 함께 PR 생성
4. 계획 실행: atlantis plan 명령으로 변경 사항 확인
5. 리뷰 과정:
   • 개발자 B: "보안 그룹 인바운드 규칙이 너무 개방적입니다."
   • 개발자 A: 수정 사항 반영 및 코드 푸시
   • 자동으로 새로운 계획 생성
6. 승인 및 적용: 리뷰 승인 후 atlantis apply 실행
7. 검증 및 병합: 새 인프라 검증 후 PR 병합

문제 해결 팁

PR이 병합된 후 리소스 관리

• 변경 사항이 필요한 경우 항상 새로운 PR을 통해 진행
• 콘솔에서 직접 변경하지 않기

리소스 삭제 관리

Atlantis는 직접적인 destroy 명령을 제공하지 않으므로:

1. 삭제할 리소스 코드를 제거하는 PR 생성
2. atlantis plan 으로 삭제될 리소스 확인
3. 팀 리뷰 후 atlantis apply 실행

결론

Helm을 사용해 Kubernetes에 Atlantis를 배포하고 Github PR 워크플로우를 구축하면 팀 협업 효율성이 크게 향상됩니다. 이 방식은 코드 품질을 높이고, 지식을 공유하며, 인프라 변경에 대한 안전성과 추적성을 제공합니다.

Terraform을 단순한 자동화 도구가 아닌 협업 기반의 '코드'로 다루는 문화를 조성하는 데 Atlantis가 큰 도움이 될 것입니다.