EKB Terraform 인프라

이 문서는 AWS EKS에서 EKB 플랫폼을 관리하기 위한 Terraform 및 Terragrunt 인프라 코드(IaC)를 포함하며, GKE, AKS 및 Bare-metal Kubernetes 지원 스텁도 포함되어 있습니다. 모든 Helm 차트 배포 및 환경 구성 템플릿이 포함되어 있습니다.

문서

문서	설명
Terragrunt 배포 가이드	새 환경 생성 및 배포를 위한 단계별 가이드
AWS 아키텍처 개요	아키텍처 개요, 구성 요소 설명 및 데이터 흐름
재해 복구 전략	DR 전략, RTO/RPO 목표, 백업 시스템 및 복구 절차
사전 요구사항 체크리스트	고객과 함께 완료할 배포 전 체크리스트

리포지토리 구조

ekb-terraform/
├── root.hcl                              # Root Terragrunt config (remote state, provider generation)
│
├── modules/                              # Reusable Terraform modules
│   ├── eks/                              # AWS EKS cluster, VPC, Karpenter, IAM, Helm releases
│   ├── aws-services/                     # ElastiCache Redis, Amazon MQ RabbitMQ
│   ├── helm/                             # Generic Helm release module
│   ├── state/                            # S3 state bucket bootstrap
│   ├── aks/                              # Azure AKS (stub)
│   ├── gke/                              # Google GKE (stub)
│   └── baremetal/                        # Bare-metal Kubernetes (stub)
│
├── terragrunt/
│   ├── .gitignore
│   └── environments/
│       ├── STATE_MANAGEMENT_README.md
│       └── env-template-folder/          # Template for new environments — copy and fill placeholders
│           ├── terragrunt.hcl            # Main environment config (cluster, Helm releases, AWS services)
│           ├── state/
│           │   └── terragrunt.hcl        # State bucket bootstrap for this environment
│           └── values/                   # Per-chart Helm values (one file per chart)
│               ├── infrastructure.yaml       # AWS Load Balancer Controller
│               ├── aws-ebs-csi-driver.yaml   # EBS CSI Driver
│               ├── karpenter.yaml            # Karpenter NodePool
│               ├── karpenter-nodeclasses.yaml# Karpenter EC2NodeClass
│               ├── karpenter-values.yaml     # Karpenter controller values
│               ├── keda.yaml                 # KEDA autoscaler
│               ├── odin-services.yaml        # EKB application services
│               ├── cloudnative-pg.yaml       # CloudNativePG operator (ENABLE_CNPG)
│               ├── ha-supabase-db.yaml       # HA Postgres cluster via CNPG (ENABLE_HA_SUPABASE_DB)
│               ├── supabase.yaml             # Supabase application stack (ENABLE_SUPABASE)
│               ├── signoz.yaml               # SigNoz observability platform (ENABLE_SIGNOZ)
│               └── signoz-k8s-infra.yaml     # SigNoz k8s-infra metrics agent (ENABLE_SIGNOZ)
│
└── helm-deployment/                      # Vendored / local Helm charts
    ├── infrastructure/                   # ALB Controller wrapper chart
    ├── odin-services/odin-services/      # EKB platform (Web, API, Celery, Automator, Ingress)
    ├── cloudnative-pg/                   # CloudNativePG operator chart
    ├── ha-supabase-db/                   # HA Supabase DB (CNPG Cluster + PgBouncer + barman backups)
    ├── supabase-kubernetes-ha/           # Full Supabase application stack
    ├── signoz/                           # SigNoz observability platform
    └── k8s-infra/                        # SigNoz k8s-infra cluster metrics agent

빠른 시작

1. 필요한 도구 설치

Terraform

# macOS
brew install terraform

# Linux
sudo apt update && sudo apt install terraform

Terragrunt

# macOS
brew install terragrunt

# Linux / macOS (manual)
curl -Lo /usr/local/bin/terragrunt \
  https://github.com/gruntwork-io/terragrunt/releases/latest/download/terragrunt_linux_amd64
chmod +x /usr/local/bin/terragrunt

kubectl 및 Helm

# macOS
brew install kubectl helm

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -m 0755 kubectl /usr/local/bin/kubectl
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

설치 확인

terraform --version
terragrunt --version
kubectl version --client
helm version
aws sts get-caller-identity

2. 새 환경 생성

새 환경은 env-template-folder를 복사하고 플레이스홀더를 채워서 생성합니다.

전체 단계별 절차는 Terragrunt 배포 가이드를 참조하세요. 전체 흐름은 다음과 같습니다:

# 1. 템플릿 복사
cp -r terragrunt/environments/env-template-folder terragrunt/environments/your-env-name

# 2. 다음 파일의 모든 <YOUR_*> 플레이스홀더를 채우세요:
#    - terragrunt/environments/your-env-name/terragrunt.hcl
#    - terragrunt/environments/your-env-name/state/terragrunt.hcl
#    - terragrunt/environments/your-env-name/values/*.yaml

# 3. 상태 버킷 부트스트랩
cd terragrunt/environments/your-env-name/state
terragrunt apply

# 4. 환경 변수 설정 및 배포
cd ../
export ENABLE_ALB_CONTROLLER=true
export WEB_DOMAIN="app.example.com"
export WEB_CERTIFICATE_ARN="arn:aws:acm:<region>:<account>:certificate/<id>"
# ... (전체 변수 목록은 TERRAGRUNT_DEPLOYMENT_GUIDE.md를 참조하세요)

terragrunt apply

서비스 활성화/비활성화 플래그

모든 선택적 서비스는 환경 변수를 통해 토글됩니다. terragrunt apply를 실행하기 전에 설정하세요.

변수	기본값	서비스
`ENABLE_ALB_CONTROLLER`	`true`	AWS Load Balancer Controller
`ENABLE_AWS_SERVICES`	`false`	ElastiCache Redis + Amazon MQ RabbitMQ
`ENABLE_CNPG`	`false`	CloudNativePG 오퍼레이터
`ENABLE_HA_SUPABASE_DB`	`false`	HA PostgreSQL 클러스터 (`ENABLE_CNPG=true` 필요)
`ENABLE_SUPABASE`	`false`	전체 Supabase 스택 (`ENABLE_HA_SUPABASE_DB=true` 필요)
`ENABLE_SIGNOZ`	`false`	SigNoz 관측 가능성 + k8s-infra 에이전트

정보

Supabase 셀프호스팅 배포 순서

Supabase 구성 요소는 순차적으로 배포되어야 합니다:

ENABLE_CNPG=true           terragrunt apply --target='helm_release.local["cloudnative-pg"]'
ENABLE_HA_SUPABASE_DB=true terragrunt apply --target='helm_release.local["ha-supabase-db"]'
ENABLE_SUPABASE=true       terragrunt apply --target='helm_release.local["supabase"]'

Helm 차트 참조

차트 (`helm-deployment/` 내)	네임스페이스	활성화 조건	설명
`infrastructure`	`infrastructure`	항상	AWS Load Balancer Controller
`odin-services/odin-services`	`default`	항상	Web, FastAPI, Celery, Automator, Ingress
`aws-ebs-csi-driver` (upstream)	`kube-system`	항상	EBS 퍼시스턴트 볼륨 드라이버
`keda` (upstream)	`keda`	항상	Pod 자동 스케일링
`cloudnative-pg`	`cnpg-system`	`ENABLE_CNPG`	PostgreSQL 오퍼레이터
`ha-supabase-db`	`ha-supabase-db`	`ENABLE_HA_SUPABASE_DB`	HA Postgres + PgBouncer + barman 백업
`supabase-kubernetes-ha`	`supabase`	`ENABLE_SUPABASE`	Kong, Auth, Storage, Studio, Realtime
`signoz`	`monitoring`	`ENABLE_SIGNOZ`	분산 추적, 메트릭, 로그
`k8s-infra` (upstream)	`monitoring`	`ENABLE_SIGNOZ`	클러스터 메트릭 DaemonSet 에이전트

모듈 참조

`modules/eks`

기본 모듈. 다음을 프로비저닝합니다:

3개 AZ에 걸친 퍼블릭/프라이빗 서브넷이 포함된 VPC
EKS 클러스터 (Kubernetes 1.33) 및 Karpenter용 매니지드 노드 그룹
Karpenter 컨트롤러 + NodePool + EC2NodeClass
IAM 역할 (클러스터, 노드 그룹, Karpenter, ALB 컨트롤러, EBS CSI 드라이버)
helm_releases 입력 맵을 통한 모든 Helm 릴리스

`modules/aws-services`

ElastiCache Redis 및 Amazon MQ RabbitMQ를 프로비저닝합니다. ENABLE_AWS_SERVICES=true일 때만 활성화됩니다.

`modules/state`

새 환경을 위한 S3 상태 버킷을 부트스트랩합니다 (버전 관리, 암호화, 퍼블릭 접근 차단).

`modules/helm`

upstream 차트 저장소와 로컬 chart_path 차트를 모두 지원하는 재사용 가능한 Helm 릴리스 모듈입니다.

환경 구성

플레이스홀더

env-template-folder의 환경별 값은 모두 <YOUR_*> 플레이스홀더를 사용합니다. 배포 전에 아무것도 남아 있지 않은지 확인하려면 다음을 실행하세요:

grep -r "<YOUR_" terragrunt/environments/your-env-name/

원격 상태

상태는 환경별로 S3에 저장됩니다. 버킷은 state/terragrunt.hcl에 의해 부트스트랩되고 root.hcl에서 참조됩니다. 명명 패턴은 ekb-terraform-state-<env-name>입니다.

시크릿

경고

민감한 값(비밀번호, API 키, 인증서 ARN)은 절대 커밋하지 않습니다. 이들은 terragrunt.hcl의 get_env() 호출에 의해 소비되는 환경 변수로 전달되거나, 배포 전에 채워야 하는 values 파일의 <YOUR_*> 플레이스홀더로 전달됩니다.

문제 해결

AWS 자격증명 확인

aws sts get-caller-identity

클러스터 접근 확인

aws eks update-kubeconfig --region <region> --name <cluster-name>
kubectl get nodes
kubectl get pods -A

ALB Controller 확인

kubectl get pods -n infrastructure | grep aws-load-balancer-controller
kubectl get ingress -A

Karpenter 확인

kubectl get pods -n kube-system | grep karpenter
kubectl get nodepools
kubectl get nodeclaims

상태 잠금 확인

# 멈춘 상태를 강제 해제하세요 (오류 메시지의 잠금 ID를 사용하세요)
cd terragrunt/environments/your-env-name
terragrunt force-unlock <lock-id>

남은 플레이스홀더가 없는지 확인

grep -r "<YOUR_" terragrunt/environments/your-env-name/

Helm 릴리스 상태 확인

helm list -A
helm status <release-name> -n <namespace>
helm get values <release-name> -n <namespace>

멀티 클라우드 지원 (계획 중)

플랫폼	상태	모듈
AWS EKS	활성	`modules/eks`
Azure AKS	스텁	`modules/aks`
Google GKE	스텁	`modules/gke`
Bare metal	스텁	`modules/baremetal`

문서​

리포지토리 구조​

빠른 시작​

1. 필요한 도구 설치​

2. 새 환경 생성​

서비스 활성화/비활성화 플래그​

Helm 차트 참조​

모듈 참조​

modules/eks​

modules/aws-services​

modules/state​

modules/helm​

환경 구성​

플레이스홀더​

원격 상태​

시크릿​

문제 해결​

멀티 클라우드 지원 (계획 중)​

문서