Repository navigation
Infra Architecture
wcorn edited this page Jun 15, 2026
·
7 revisions
Kubernetes GitOps 기반 인프라 구조를 정의한다. 모든 인프라 변경은 이 아키텍처를 따른다.
| 원칙 | 설명 |
|---|---|
| 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 커밋 금지 |
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)
root-app (argocd/app-of-apps/)
│
│ infra/argocd/applications/ 디렉토리를 감시
│
├── {name}-app.yaml → infra/helm/{name}/ (Helm Chart)
├── {name}-app.yaml → infra/helm/{name}/
└── ...
-
infra/argocd/applications/경로를 source로 지정 - Auto Sync 활성화 (prune, selfHeal)
- 하위 Application YAML 추가만으로 새 컴포넌트 배포
각 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 어노테이션으로 제어한다.
- 허용된 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.
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_bootstrapskip → 운영 클러스터에 재실행해도 무중단(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).
upstream chart를 dependency로 감싸고 values.yaml로 설정을 오버라이드한다.
# Chart.yaml
dependencies:
- name: {upstream-chart}
version: {version}
repository: {helm-repo-url}# values.yaml
{upstream-chart}:
{설정 키}: {값}BE, FE, MySQL, Redis 등 직접 작성하는 Chart는 templates/에 리소스를 정의한다.
helm/{name}/
├── Chart.yaml
├── values.yaml
└── templates/
├── deployment.yaml 또는 statefulset.yaml
├── service.yaml
└── sealedsecret.yaml (필요 시)
외부 (인터넷)
↓ 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 operator + API server proxy로 맥에서
kubectl을 안전하게 — 공개 노출 없이(데이터 P2P, 컨트롤 플레인만 Tailscale 클라우드). 신원 기반 RBAC. - **subnet router(Connector)**가
192.168.0.0/24를 tailnet에 광고 → CI 러너/원격 클라이언트가 노드 LAN에 접근(노드 호스트 설치 0). Ansible 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 파이프라인
Loki(로그) · Thanos(메트릭) · Tempo(트레이스) · Alloy(수집) · Grafana(조회) + S3 장기저장으로 구성된 self-hosted LGTM 스택을 운영한다.
평문 Secret → kubeseal로 암호화 → SealedSecret YAML → Git 커밋
↓
ArgoCD 동기화 → Sealed Secrets Controller → Secret 복호화 → Pod에 주입
- SealedSecret은 클러스터의 공개키로 암호화되어 Git에 안전하게 저장
- 시크릿이 필요한 Chart는
templates/sealedsecret.yaml에 암호화된 데이터를 정의 - 평문
.env,SecretYAML은 절대 Git에 커밋하지 않는다
- 분산 블록 스토리지(Longhorn)를 기본 StorageClass로 사용
- PersistentVolumeClaim으로 영구 데이터 관리 (DB 등)
- 캐시(Redis)는 영구 스토리지 없이 인메모리 운영
# docker-compose.yml
services:
mysql: # 운영과 동일 버전
redis: # 운영과 동일 버전
be: # Dockerfile.dev (bootRun)- 운영 환경과 동일한 DB/캐시 버전 사용
- BE는
Dockerfile.dev로 핫 리로드 개발 - FE는 로컬
npm run dev로 개발 (Vite 프록시 → BE 컨테이너)
-
infra/helm/{name}/Chart.yaml— dependency에 upstream chart 등록 -
infra/helm/{name}/values.yaml— 커스텀 설정 -
helm dependency build로 Chart.lock 생성 -
infra/argocd/applications/{name}-app.yaml— Application 리소스 생성 - 새 네임스페이스가 필요하면
infra/argocd/project/project.yaml에 추가
-
infra/helm/{name}/— Chart.yaml + values.yaml + templates/ 작성 -
infra/argocd/applications/{name}-app.yaml— Application 리소스 생성 -
.github/workflows/{name}-cd.yml— 이미지 빌드/푸시 워크플로우 생성 - ArgoCD Image Updater에 이미지 감시 대상 추가
| 결정 | 대안 | 선택 이유 |
|---|---|---|
| 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 기반 업데이트 | 동일 태그의 이미지 변경 감지 가능, 이미지 무결성 보장 |