— 혼란 없는 Kubernetes 배포를 위한 깔끔한 구조 설계
“코드를 잘 짜는 것보다, 코드를 잘 관리하는 구조가 더 중요하다.”
🧩 1. 기본 설계 철학
Git 저장소 구조는 단순히 ‘디렉토리 정리’가 아니라,
배포 파이프라인의 흐름, 환경 분리, 마이크로서비스의 독립성을 반영해야 합니다.
🧠 목표는 3가지입니다:
- 환경별 분리 (dev / staging / prod)
- 서비스별 독립 관리
- 변경 이력 추적 + 배포 통제 가능
📐 2. GitOps용 표준 디렉토리 구조 예시
gitops-repo/
├── apps/
│ ├── auth-service/
│ │ ├── base/ # Helm chart 또는 Kustomize 공통 설정
│ │ ├── overlays/
│ │ │ ├── dev/
│ │ │ ├── staging/
│ │ │ └── prod/
│ │ └── README.md
│ ├── order-service/
│ └── payment-service/
├── infra/
│ ├── ingress-nginx/
│ ├── cert-manager/
│ ├── monitoring/
│ └── logging/
├── clusters/
│ ├── dev/
│ ├── staging/
│ └── prod/
├── projects/ # ArgoCD Project 설정
├── applications/ # ArgoCD Application YAML 정의
└── README.md
📦 3. 구조 설명
🔹 /apps/
서비스 단위의 애플리케이션을 정의합니다.
- base/: 공통 설정 (deployment, service 등 Helm/Kustomize 원본)
- overlays/: 환경별 설정 (replica 수, 이미지 tag, 리소스 제한 등)
values.yaml,kustomization.yaml등 선언형 구성
🔹 /infra/
공통 인프라 리소스를 관리합니다.
(모니터링, 인증서, 인그레스, 로그 수집 등)
예:
infra/
├── ingress-nginx/
│ ├── base/
│ └── overlays/
│ ├── dev/
│ └── prod/
🔹 /clusters/
클러스터 환경별 구성 정보.
RBAC, 네임스페이스, 리소스 제한, AppSet, Secrets 매핑 등
🔹 /applications/
ArgoCD에서 관리할 Application 리소스 정의
예:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: auth-service-dev
spec:
source:
repoURL: https://github.com/org/gitops-repo.git
targetRevision: main
path: apps/auth-service/overlays/dev
destination:
server: https://kubernetes.default.svc
namespace: auth-dev
project: default
syncPolicy:
automated:
prune: true
selfHeal: true
🔹 /projects/
ArgoCD의 AppProject 정의
- 서비스 그룹별 리소스 경계 설정
- namespace, destination 제한
🧰 4. 실제 브랜치 전략 (선택사항)
| 전략 | 설명 |
|---|---|
단일 브랜치 (main) | 디렉토리로 환경 구분 → 단순함, ArgoCD 관리 쉬움 |
멀티 브랜치 (dev, staging, prod) | 브랜치로 배포 환경 구분 → 강한 분리 가능, 충돌 위험 |
🔐 5. 보안·운영 팁
- Secrets는 Git에 직접 커밋 금지
→ Sealed Secrets, External Secrets, HashiCorp Vault 연동 - 디렉토리별 권한 설정 가능 (Monorepo)
→ 서비스별 책임 개발자 지정 가능 - Pull Request 기반 배포 승인 흐름 구성
→ CI에서helm lint,kubeval등 자동 검증
🧠 6. 확장 전략
| 목적 | 확장 방식 |
|---|---|
| 다중 클러스터 운영 | /clusters/region-1/, /clusters/region-2/ 구분 |
| 멀티테넌시 | ArgoCD Project + Namespace 격리 |
| GitOps + Policy | Open Policy Agent (OPA), Kyverno와 통합 |
| Helm 대체 | Kustomize, Jsonnet 등도 사용 가능 |
✅ 마무리 요약
| 구성요소 | 역할 |
|---|---|
apps/ | 서비스별 정의 및 배포 상태 |
infra/ | 공통 인프라 리소스 |
applications/ | ArgoCD 관리 대상 App 선언 |
projects/ | App의 그룹, 권한, 범위 관리 |
clusters/ | 클러스터 전용 설정 및 확장 |
Git 저장소는 단순 코드 저장소가 아닌,
**운영 상태 자체의 진실된 기준(Single Source of Truth)**입니다.