클러스터 개요
목적
Lumie의 인프라 클러스터는 Terraform과 Ansible로 부트스트랩되고 이후 Argo CD App-of-Apps로 운영되는 OCI 호스팅 K3s 환경입니다. 이 페이지는 클러스터 프 로비저닝, 부트스트랩 순서, 공유 플랫폼 인프라를 변경하는 엔지니어를 위한 overview 문서입니다.
Kubernetes, Terraform, Ansible, Services, Networking Overview로 더 깊이 들어가기 전에 방향을 잡는 용도로 이 페이지를 사용하세요.
소스 경로
| 경로 | 역할 |
|---|---|
lumie-infra/provision/terraform/ | OCI 네트워킹, 컴퓨트, 블록 볼륨, 로드 밸런서 프로비저닝 |
lumie-infra/provision/ansible/ | OS 준비, K3s 설치, 스토리지 마운트, kubeconfig 가져오기, Argo CD 부트스트랩 |
lumie-infra/applications/kustomization.yaml | cluster-bootstrap을 포함한 최상위 Argo CD 애플리케이션 카탈로그 |
lumie-infra/bootstrap/kustomization.yaml | MinIO, Zot, Vault, Gitea 같은 sync wave -1 기반 앱 |
lumie-infra/platform/kustomization.yaml | CoreDNS config, Traefik config, cert-manager, RabbitMQ, KEDA 같은 클러스터 전역 플랫폼 앱 |
lumie-infra/applications/cluster-bootstrap/ | ClusterIssuer, StorageClass 같은 sync wave -2 클러스터 범위 리소스 |
소유권 경계
| 계층 | 저장소 내 소유자 | 제어하는 것 |
|---|---|---|
| OCI 인프라 | provision/terraform | VCN, 서브넷, 피어링, 인스턴스, MinIO 블록 볼륨, 퍼블릭 NLB |
| 노드 부트스트랩 | provision/ansible | Ubuntu 준비, K3s 설치, 레지스트리 미러, MinIO 디스크 마운트, 부트스트랩 시크릿, 초기 Argo CD 설치 |
| 부트스트랩 이후 desired state | bootstrap/, platform/, storage/, security/, observability/, applications/의 Argo CD 애플리케이션 | 네임스페이스, Helm 릴리스, 원시 매니페스트, 지속적 self-heal |
| 제품 워크로드 | lumie-infra/applications/lumie/** 및 앱 저장소 | 워크로드 배포 형태, ingress, 시크릿 연결, 스케일링, 서비스 노출 |
| Day-two 검증 | 라이브 클러스터에 대한 읽기 전용 kubectl | Git 상태와 라이브 상태가 여전히 일치하는지 확인 |
의도된 제어 흐름은 단방향입니다. Terraform이 호스트와 네트워크를 만들고, Ansible이 그 호스트를 K3s 클러스터로 전환한 뒤 Argo CD를 심고, 이후에는 Argo CD가 거의 모든 정상 상태 Kubernetes 오브젝트를 소유합니다.
런타임 흐름
클러스터 형태
코드 기준 현재 설계는 다음과 같습니다.
0214와0213두 OCI 계정을 로컬 피어링 게이트웨이로 연결합니다.0214계정에 K3s 서버 1대를 두고, 두 계정에 워커를 분산 배치합니다.- OCI layer-4 NLB가
:443을 워커 노드로 전달하는 퍼블릭 HTTPS ingress를 사용합니다. - 클러스터 범위 부트스트랩 리소스는 일반 플랫폼 애플리케이션보다 먼저 적용됩니다.
- Vault, RabbitMQ, observability, CI/CD 같은 공유 플랫폼 서비스는 Argo CD 애플리케이션으로 관리됩니다.
2026년 6월 14일에 확인한 라이브 클러스터는 k3s-master, k3s-worker-2, k3s-worker-3, k3s-worker-4의 네 개 준비 완료 노드를 보고했습니다. 체크인된 terraform.tfvars.example에는 아직 worker-1이 포함되어 있으므로 이를 권위 있는 값이 아니라 예시로만 취급하세요.
운영 메모
- Kubernetes API 조인 대상은 Ansible defaults에
10.0.0.241:6443로 하드코딩되어 있으므로, 마스터 프라이빗 IP가 바뀌면 워커 재조인 작업 전에 inventory와 group vars에 반영해야 합니다. - 로컬 프런트엔드 개발 워크플로는 Next.js 앱을 클러스터 안에서 실행하지 않습니다.
dev.lumie-infra.com에는 dev API ingress만 있고, 프런트엔드는 Tilt와 HMR을 통해 로컬에서 실행됩니다. 자세한 내용은 Tilt를 참고하세요. - 클러스터 부트스트랩은 두 개의 wave로 나뉩니다. 클러스터 범위 선행 조건은 sync wave
-2의cluster-bootstrap이, MinIO, Zot, Vault, Gitea는 sync wave-1의bootstrap이 담당합니다. - Argo CD self-heal이 켜져 있으므로 관리 대상 리소스에 대한 즉석
kubectl apply변경은 이후 sync에서 다시 Git 상태로 되돌아갈 수 있습니다.
알아둘 계약 드리프트
검사한 소스는 몇 군데에서 서로 다릅니다.
lumie-infra/README.md는 여전히 Kong을 ingress 계층으로 설명하지만,lumie-infra/AGENTS.md, 플랫폼 매니페스트, 라이브 클러스터는 모두 Traefik이 활성 ingress controller임을 보여줍니다.lumie-infra/README.md는 여전히 5노드 클러스터와 오래된 서비스 인벤토리를 설명합니다. 하지만 2026년 6월 14일의 라이브 클러스터 점검에서는 준비 완료 노드가 4개였습니다.- 저장소에는 아직
bootstrap/kong/이 남아 있지만,lumie-infra/bootstrap/kustomization.yaml에는bootstrap/kong/argocd.yaml이 등록되어 있지 않고 라이브argocdApplication이나kong네임스페이스도 존재하지 않습니다.
이 불일치는 운영자에게 중요합니다. 저장소 안에 활성 desired state와 보존된 레거시 아티팩트가 함께 존재하기 때문입니다.
장애 지점
| 장애 지점 | 영향 |
|---|---|
| Terraform 네트워킹 드리프트 | 워커가 마스터 API 또는 퍼블릭 ingress에 도달하지 못할 수 있음 |
| Ansible 부트스트랩 드리프트 | 새 노드가 조인되지 않거나, MinIO 디스크가 마운트되지 않거나, Argo CD가 올바르게 시드되지 않을 수 있음 |
| 부트스트랩 중 Vault 비가용 | 해당 앱이 sync되더라도 하위 VaultStaticSecret 소비자가 계속 대기 상태에 머묾 |
| Argo CD 앱 등록 누락 | Git에 디렉터리가 있어도 실제 클러스터에는 전혀 반영되지 않을 수 있음 |
| Git 밖에서의 라이브 핫픽스 | 다음 sync에서 Argo CD가 이를 덮어쓸 수 있음 |
검증
저장소와 클러스터를 모두 확인하세요.
kubectl get nodes -o wide
kubectl get applications -n argocd
kubectl get ns
rg -n "cluster-bootstrap|bootstrap|platform|applications" \
lumie-infra/applications/kustomization.yaml \
lumie-infra/bootstrap/kustomization.yaml \
lumie-infra/platform/kustomization.yaml
프로비저닝 변경을 검토할 때는 다음 계층별 문서를 계속 참고하세요.