Skip to content

Infra Architecture

wcorn edited this page Jun 15, 2026 · 7 revisions

인프라 아키텍처

Kubernetes GitOps 기반 인프라 구조를 정의한다. 모든 인프라 변경은 이 아키텍처를 따른다.

1. 설계 원칙

원칙 설명
GitOps 모든 인프라는 Git에 선언적으로 정의한다. kubectl apply, helm install 직접 실행 금지
App of Apps ArgoCD가 루트 Application을 통해 하위 Application을 관리한다
Wrapper Chart Helm Chart는 upstream chart를 dependencies로 감싸고 values.yaml로 커스터마이징한다
Sealed Secrets 시크릿은 암호화된 SealedSecret으로 Git에 커밋한다. 평문 Secret 커밋 금지

2. 디렉토리 구조

infra/
├── argocd/
│   ├── app-of-apps/
│   │   └── root-app.yaml               # 루트 Application (진입점)
│   ├── project/
│   │   └── project.yaml                 # AppProject (RBAC, 네임스페이스 제한)
│   └── applications/
│       └── {name}-app.yaml              # 개별 Application (Helm 참조)
│
├── helm/
│   └── {name}/
│       ├── Chart.yaml                   # dependencies로 upstream chart 참조
│       ├── Chart.lock                   # dependency lock
│       ├── values.yaml                  # 커스텀 설정
│       └── templates/                   # 추가 리소스 (필요 시)
│           └── {resource}.yaml
│
├── ansible/                             # 노드 부트스트랩 IaC (§4)
│   ├── site.yml                         # 롤 순서: node_os→…→argocd_bootstrap
│   ├── inventory.ini
│   └── roles/{role}/
│
└── terraform/                           # AWS (Route53, IAM/OIDC, S3 backend)

3. ArgoCD App of Apps 패턴

root-app (argocd/app-of-apps/)
  │
  │  infra/argocd/applications/ 디렉토리를 감시
  │
  ├── {name}-app.yaml  →  infra/helm/{name}/  (Helm Chart)
  ├── {name}-app.yaml  →  infra/helm/{name}/
  └── ...

루트 Application

  • infra/argocd/applications/ 경로를 source로 지정
  • Auto Sync 활성화 (prune, selfHeal)
  • 하위 Application YAML 추가만으로 새 컴포넌트 배포

개별 Application

각 Application은 하나의 Helm Chart를 참조한다.

# infra/argocd/applications/{name}-app.yaml
spec:
  source:
    path: infra/helm/{name}
  destination:
    namespace: {target-namespace}
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

배포 순서가 필요한 경우 sync-wave 어노테이션으로 제어한다.

AppProject

  • 허용된 source repository와 destination namespace를 제한
  • 새 네임스페이스가 필요하면 project.yaml에 추가
  • AppProject 자신도 GitOps로 관리 — root앱은 applications/만 감시해 project.yaml은 어느 앱에도 안 잡혀 수동 apply가 필요했다. orino-project 앱(applications/orino-project-app.yaml, source=argocd/project/)을 둬서 project 변경도 머지만으로 반영(PR #495). 실수 삭제 방지로 prune: false.

4. 노드 부트스트랩 (Ansible)

ArgoCD가 워크로드를 GitOps로 관리한다면, 그 ArgoCD가 돌 수 있을 때까지(노드 OS → 클러스터 → ArgoCD)는 Ansible이 코드로 만든다. OS 설치만 수동, 그 위 전부 IaC. (infra/ansible/, 에픽 #461)

[수동] OS 설치
   │
   ▼  Ansible (infra/ansible/site.yml, 롤 순서대로)
node_os ─→ kubeadm_prereqs ─→ container_runtime ─→ kubeadm ─→ argocd_bootstrap
 sysctl     커널모듈·sysctl     containerd 서비스    init/join   ArgoCD helm 설치
 (inotify)  ·swap off          보장               +Calico CNI  +AppProject+root
   │
   ▼  여기서부터 ArgoCD 인수 (App of Apps, §3)
워크로드·인프라 차트 (GitOps)
롤 역할
node_os 커널 sysctl (inotify 고갈 대응 등)
kubeadm_prereqs 커널 모듈(overlay/br_netfilter) + 네트워크 sysctl(ip_forward/bridge-nf-call) + swap off
container_runtime containerd 서비스 보장 (config 무중단 위해 미변경)
kubeadm 클러스터 init(control-plane)/join(worker) + Calico CNI
argocd_bootstrap ArgoCD helm 설치(chicken-and-egg 라 GitOps 밖) + AppProject·root(App of Apps) apply

설계 원칙

  • 멱등 + 가드: 각 롤은 "이미 된 상태"를 감지해 skip한다. 기존 멤버 노드(kubelet.conf 존재)엔 kubeadm 블록 전체 skip, ArgoCD 설치돼 있으면 argocd_bootstrap skip → 운영 클러스터에 재실행해도 무중단(changed=0). 새 노드에서만 프로비저닝 경로가 돈다.
  • 현 클러스터 역공학: 버전·CIDR·CNI를 운영 노드에서 그대로 떠와 핀(k8s 1.34.5, podSubnet 10.244.0.0/16, Calico v3.31.4, argo-cd v9.4.10).
  • 한계: init/join·ArgoCD 설치 경로는 운영 클러스터가 하나뿐이라 실증 미검증(역공학) — 차기 노드 증설이 첫 실전 검증.
  • CI/CD: infra/ansible/** 변경은 PR=lint, main 머지=자동 apply (§7). NAT 뒤 노드 접근은 Tailscale subnet router 경유(§6).

5. Helm Chart 구조

Wrapper Chart (외부 의존성이 있는 경우)

upstream chart를 dependency로 감싸고 values.yaml로 설정을 오버라이드한다.

# Chart.yaml
dependencies:
  - name: {upstream-chart}
    version: {version}
    repository: {helm-repo-url}
# values.yaml
{upstream-chart}:
  {설정 키}: {값}

Custom Chart (자체 리소스인 경우)

BE, FE, MySQL, Redis 등 직접 작성하는 Chart는 templates/에 리소스를 정의한다.

helm/{name}/
├── Chart.yaml
├── values.yaml
└── templates/
    ├── deployment.yaml 또는 statefulset.yaml
    ├── service.yaml
    └── sealedsecret.yaml (필요 시)

6. 네트워크 구조

외부 트래픽 (집 회선 직결)

외부 (인터넷)
    ↓   Route53  (orino.dev + *.orino.dev wildcard A → 집 공인 IP)
공유기 443 포워딩
    ↓
MetalLB(L2) VIP 192.168.0.240
    ↓
Istio Gateway (443 HTTPS, cert-manager wildcard TLS 종단)
    ↓   Istio VirtualService (호스트 기반)
    ├→ orino.dev           → FE (80)
    ├→ api.orino.dev       → BE (8080)
    ├→ img.orino.dev       → MinIO (9000)
    └→ telemetry.orino.dev → Alloy (Faro)
    ↓
Pod (Istio sidecar 자동 주입)
  • Cloudflare를 제거하고 집 회선 직결로 전환 — 무료 CF anycast의 LAX(미국) 라우팅 지연 해소. TTFB 872ms → 12~26ms (ELOG-009).
  • 가비아 도메인의 NS를 Route53로 위임, wildcard A레코드/인증서 → 새 서브도메인은 VirtualService만 추가.
  • **MetalLB(L2)**가 LAN VIP 할당(공유기 443 포워딩 대상), **cert-manager + Let's Encrypt(Route53 DNS-01)**가 wildcard TLS 자동 발급/갱신.
  • 동적 공인 IP는 정적 A레코드 + 변경 시 수동 갱신(단일 사용자, DDNS 보류).
  • orino 네임스페이스에 istio-injection: enabled 라벨로 sidecar 자동 주입.

원격 운영 접근 (Tailscale)

  • Tailscale operator + API server proxy로 맥에서 kubectl을 안전하게 — 공개 노출 없이(데이터 P2P, 컨트롤 플레인만 Tailscale 클라우드). 신원 기반 RBAC.
  • **subnet router(Connector)**가 192.168.0.0/24를 tailnet에 광고 → CI 러너/원격 클라이언트가 노드 LAN에 접근(노드 호스트 설치 0). Ansible CI/CD가 이 경로를 사용.

7. CI/CD 파이프라인

PR → CI (빌드/테스트/린트) → 머지 → CD (이미지 빌드 → GHCR)
    → Image Updater (digest 감지 → Git 커밋) → ArgoCD (클러스터 동기화)
  • 앱(BE/FE): 이미지 빌드 → GHCR → Image Updater → ArgoCD.
  • 인프라(Terraform/Ansible)도 CI/CD 자동화 — PR=plan/lint, main 머지=apply. Terraform은 AWS OIDC(정적 키 없음), Ansible은 Tailscale subnet router 경유로 노드 적용.

상세: CI/CD 파이프라인

8. 관측성 스택

Loki(로그) · Thanos(메트릭) · Tempo(트레이스) · Alloy(수집) · Grafana(조회) + S3 장기저장으로 구성된 self-hosted LGTM 스택을 운영한다.

상세: 관측성 (Observability)

9. 시크릿 관리

평문 Secret → kubeseal로 암호화 → SealedSecret YAML → Git 커밋
    ↓
ArgoCD 동기화 → Sealed Secrets Controller → Secret 복호화 → Pod에 주입
  • SealedSecret은 클러스터의 공개키로 암호화되어 Git에 안전하게 저장
  • 시크릿이 필요한 Chart는 templates/sealedsecret.yaml에 암호화된 데이터를 정의
  • 평문 .env, Secret YAML은 절대 Git에 커밋하지 않는다

10. 스토리지

  • 분산 블록 스토리지(Longhorn)를 기본 StorageClass로 사용
  • PersistentVolumeClaim으로 영구 데이터 관리 (DB 등)
  • 캐시(Redis)는 영구 스토리지 없이 인메모리 운영

11. 로컬 개발 환경

# docker-compose.yml
services:
  mysql:    # 운영과 동일 버전
  redis:    # 운영과 동일 버전
  be:       # Dockerfile.dev (bootRun)
  • 운영 환경과 동일한 DB/캐시 버전 사용
  • BE는 Dockerfile.dev로 핫 리로드 개발
  • FE는 로컬 npm run dev로 개발 (Vite 프록시 → BE 컨테이너)

12. 새 컴포넌트 추가 가이드

외부 Helm Chart 추가 시

  1. infra/helm/{name}/Chart.yaml — dependency에 upstream chart 등록
  2. infra/helm/{name}/values.yaml — 커스텀 설정
  3. helm dependency build 로 Chart.lock 생성
  4. infra/argocd/applications/{name}-app.yaml — Application 리소스 생성
  5. 새 네임스페이스가 필요하면 infra/argocd/project/project.yaml에 추가

자체 애플리케이션 추가 시

  1. infra/helm/{name}/ — Chart.yaml + values.yaml + templates/ 작성
  2. infra/argocd/applications/{name}-app.yaml — Application 리소스 생성
  3. .github/workflows/{name}-cd.yml — 이미지 빌드/푸시 워크플로우 생성
  4. ArgoCD Image Updater에 이미지 감시 대상 추가

13. 선택 근거

결정 대안 선택 이유
ArgoCD + GitOps Flux, Jenkins CD App of Apps 패턴으로 선언적 관리, UI 제공, 커뮤니티 성숙
Wrapper Chart 직접 manifest 작성 upstream 업데이트 추적 용이, values.yaml만 관리
Sealed Secrets External Secrets, Vault 외부 시크릿 서비스 불필요, Git만으로 완결
집 회선 직결 (Route53 + MetalLB + cert-manager) Cloudflare Tunnel 무료 CF anycast의 LAX 라우팅 지연 제거(872ms→~20ms), 비용↓. DDoS 방어는 상실하나 개인 프로젝트라 허용
Tailscale operator (원격 kubectl) API 공개 노출, 정적 kubeconfig 공개 노출 없이(P2P) 신원 기반 접근. self-hosted(Headscale)는 단일노드 운영부담↑
Ansible (노드 부트스트랩 IaC) 수동 노드 설정, Talos·k3s 등 OS 설치 제외 노드~ArgoCD 부트스트랩 전 구간을 멱등 코드로(§4). 기존 클러스터 무중단 가드, 새 노드 재현. 기존 kubeadm 클러스터를 갈지 않고 역공학
Istio Nginx Ingress, Traefik 서비스 메시 (mTLS, 트래픽 관리), Gateway API 지원
Longhorn local-path, NFS 분산 복제로 노드 장애 대응, 스냅샷/백업
Image Updater + digest tag 기반 업데이트 동일 태그의 이미지 변경 감지 가능, 이미지 무결성 보장

Clone this wiki locally