쿠버네티스 실습: Terraform + ArgoCD + Helm으로 완전 자동화된 IaC 파이프라인 구축하기

쿠버네티스 실습: Terraform + ArgoCD + Helm으로 완전 자동화된 IaC 파이프라인 구축하기

이전 글에서는 멀티클러스터 + 글로벌 트래픽 전환(Geo Failover) 환경을 완성했습니다.
이제 인프라를 한 단계 더 진화시켜, 코드 한 줄로 클러스터 생성 → 배포 → DR 세팅까지 자동화하는
IaC (Infrastructure as Code) 기반 파이프라인을 구축합니다.

---

1) Infrastructure as Code란?

**IaC (인프라스트럭처 코드화)**는 서버, 네트워크, 스토리지, DNS, 쿠버네티스 등
모든 인프라 구성을 Git에 선언적으로 관리하고,
변경 시 git commit → pipeline → apply 만으로 자동 반영하는 방식을 말합니다.

항목 기존 방식 IaC 방식

인프라 생성	수동 (콘솔, CLI)	코드 기반 자동 생성
변경 관리	문서 또는 수작업	Git Commit 이력 관리
배포 자동화	별도 스크립트 필요	GitOps 연동 자동화
복구/복제	어렵고 불안정	코드로 재현 가능

이번 실습에서는 Terraform + ArgoCD + Helm을 조합해
쿠버네티스 인프라와 앱 배포를 모두 코드로 관리합니다.

---

2) 전체 아키텍처 개요

GitHub Repo (infra + apps)
│
├── Terraform : 클러스터 및 클라우드 인프라 생성
│
├── Helm      : 앱 설정 관리 및 템플릿 배포
│
└── ArgoCD    : GitOps로 상태 동기화 및 자동 배포

배포 과정은 다음과 같이 동작합니다.

1️⃣ Terraform으로 EKS / GKE / AKS 클러스터 자동 생성
2️⃣ Helm으로 쿠버네티스 앱 차트 관리
3️⃣ ArgoCD가 Git 상태를 자동 Sync
4️⃣ Prometheus, Velero, External-DNS, DR 시스템 자동 반영

---

3) 디렉토리 구조

반응형

fuelstation-infra/
│
├── terraform/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── eks/
│       ├── cluster.tf
│       ├── nodegroup.tf
│       └── iam.tf
│
├── helm/
│   ├── charts/
│   │   ├── nestjs/
│   │   ├── nextjs/
│   │   └── redis/
│   └── values/
│       ├── dev.yaml
│       └── prod.yaml
│
└── argocd/
    ├── apps/
    │   ├── backend-app.yaml
    │   ├── frontend-app.yaml
    │   └── database-app.yaml
    └── project.yaml

---

4) Terraform으로 EKS 클러스터 생성 (AWS 예시)

main.tf

provider "aws" {
  region = var.region
}

module "eks" {
  source          = "terraform-aws-modules/eks/aws"
  cluster_name    = "fuelstation-cluster"
  cluster_version = "1.30"
  subnets         = var.subnets
  vpc_id          = var.vpc_id
  node_groups = {
    default = {
      desired_capacity = 3
      max_capacity     = 5
      min_capacity     = 2
      instance_types   = ["t3.medium"]
    }
  }
}

output "cluster_endpoint" {
  value = module.eks.cluster_endpoint
}

실행:

terraform init
terraform plan
terraform apply -auto-approve

결과:

Apply complete! Resources: 32 added.
cluster_endpoint = https://XXXX.eks.amazonaws.com

---

5) Helm Chart로 애플리케이션 구성

예: charts/nestjs/templates/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-backend
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
      - name: backend
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        ports:
        - containerPort: 3001

values/prod.yaml

replicaCount: 3
image:
  repository: 1234567890.dkr.ecr.ap-northeast-2.amazonaws.com/nestjs
  tag: latest

---

6) ArgoCD Application 정의

argocd/apps/backend-app.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: backend
  namespace: argocd
spec:
  project: default
  source:
    repoURL: 'https://github.com//fuelstation-infra.git'
    targetRevision: main
    path: helm/charts/nestjs
    helm:
      valueFiles:
      - values/prod.yaml
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: team-a
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

ArgoCD에 적용:

kubectl apply -f argocd/apps/backend-app.yaml

→ Git Commit → ArgoCD Sync → 자동 배포 완료.

---

7) IaC 파이프라인 자동화 (GitHub Actions 예시)

.github/workflows/deploy.yaml

name: Deploy Infrastructure
on:
  push:
    branches: [ main ]
jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
      - name: Terraform Init & Apply
        run: |
          cd terraform
          terraform init
          terraform apply -auto-approve
  notify:
    needs: terraform
    runs-on: ubuntu-latest
    steps:
      - name: Notify ArgoCD Sync
        run: |
          curl -X POST https://argocd-server/api/webhook -d '{"event":"sync"}'

→ Git Push 한 번으로 클러스터 생성 → 배포 → 상태동기화 → 알림까지 완전 자동화.

---

8) Observability & DR 통합

Terraform이 Helm Chart 배포 시 다음 Add-on도 자동 설치되도록 구성:

• Prometheus / Grafana / Kiali / Jaeger
• Velero 백업 / S3 저장소
• External-DNS + Ingress Controller
• ArgoCD Self-heal

→ 코드 한 줄로 전체 DevOps 환경 생성 가능.

---

9) 고급 운영 전략

구성 요소 관리 주체 자동화 방식 설명

클러스터 생성	Terraform	GitHub Actions	인프라 프로비저닝
애플리케이션 배포	ArgoCD	GitOps	선언적 배포 관리
환경 설정	Helm	Values 파일	다중 환경(dev/prod)
백업/DR	Velero	Cron + Webhook	자동 복원 체계
모니터링	Prometheus	Helm Add-on	SLA 감시

---

10) 정리

• Terraform으로 인프라 생성
• Helm으로 설정 관리
• ArgoCD로 자동 배포
• GitHub Actions로 모든 프로세스 트리거
  → 코드 한 줄로 완전한 쿠버네티스 DevOps 환경(IaC) 완성

다음 글에서는 이 IaC 환경을 확장해
Secret Manager, OIDC 인증, Vault 연동을 통한 보안 중심 DevSecOps 파이프라인을 구축하겠습니다.

---

 

쿠버네티스,Terraform,ArgoCD,Helm,GitOps,IaC,DevOps,자동배포,인프라코드화,K8s실습

 

 

🔍 개선 및 확장 제안

1️⃣ 제목 개선 (SEO 강화 버전)

"Terraform + ArgoCD + Helm으로 완전 자동화된 Kubernetes IaC 파이프라인 구축하기 (실전 가이드)"

→ Kubernetes, IaC, Terraform, ArgoCD, Helm, 자동화 키워드가 모두 포함되어
검색 유입률이 최대화됩니다.

---

2️⃣ 내용 강화 포인트

✅ (1) IaC 선언형 vs 명령형 비교 도표 추가

독자들이 GitOps 철학을 더 직관적으로 이해할 수 있도록 아래처럼 보완:

구분 명령형(Imperative) 선언형(Declarative / IaC)

명령 방식	"이 서버 만들어라"	"이 상태가 되어 있어야 한다"
관리 단위	명령 단위	상태(State) 단위
예시	kubectl create ...	apply 또는 sync
변경 추적	어렵다	Git 이력으로 가능

---

✅ (2) GitOps 동작 흐름 다이어그램 추가

아래 예시를 추가로 시각화하면 이해도가 급상승합니다.

개발자 → Git Push
       ↓
GitHub Actions (Terraform Apply)
       ↓
EKS 클러스터 생성 / Helm Chart 배포
       ↓
ArgoCD → Git 상태 감시 → 자동 Sync
       ↓
쿠버네티스에 애플리케이션 반영

---

✅ (3) Terraform 백엔드 예시 (backend "s3") 추가

프로젝트를 실무형으로 강화하기 위해 Terraform의 state 관리 예시를 추가하면 좋습니다.

terraform {
  backend "s3" {
    bucket = "fuelstation-terraform-state"
    key    = "eks/terraform.tfstate"
    region = "ap-northeast-2"
  }
}

→ “모든 인프라 상태를 원격 S3에 저장하고, 팀 협업 시에도 충돌 없이 동시 작업 가능”

---

✅ (4) ArgoCD와 Helm 연계 구조 시각화

Git Repo
├── terraform/
├── helm/
└── argocd/
      └── apps/
           └── backend-app.yaml (Helm Chart 참조)

→ ArgoCD Application이 Helm 경로를 직접 바라보는 구조를 명확히 강조.

---

✅ (5) 실무 팁 추가

🔸 Tip: Terraform으로 만든 EKS 클러스터에 ArgoCD를 자동 설치하려면
local-exec 또는 helm_release 모듈을 이용해 ArgoCD manifest를 바로 배포할 수 있습니다.

resource "helm_release" "argocd" {
  name       = "argocd"
  repository = "https://argoproj.github.io/argo-helm"
  chart      = "argo-cd"
  namespace  = "argocd"
  create_namespace = true
}

---

3️⃣ 다음 글(예고편) 예시

다음 글: Terraform + Vault + OIDC로 완성하는 DevSecOps 파이프라인
IaC 환경에 보안 레이어를 더해,
“비밀값이 코드에 남지 않는 완전 자동화된 인증 체계”를 실습합니다.

---

4️⃣ 블로그용 메타데이터 (SEO)

title: Terraform + ArgoCD + Helm으로 완전 자동화된 Kubernetes IaC 파이프라인 구축하기
description: Terraform, ArgoCD, Helm을 이용해 쿠버네티스 인프라를 완전 자동화하는 실전 가이드. GitOps 기반 IaC 구축부터 클러스터 생성, 자동 배포까지 단계별 예제.
keywords: 쿠버네티스, IaC, Terraform, ArgoCD, Helm, GitOps, DevOps, 자동화, 인프라코드, EKS
author: 조훈창
published_at: 2025-10-23
series: Kubernetes 실전 IaC 시리즈
reading_time: 12분

---