Kubernetes
목적
Lumie는 관리형 Kubernetes 서비스가 아니라 K3s 위에서 실행됩니다. 이 페이지는 Kubernetes 계층 자체를 다루는 레퍼런스 문서로, 클러스터 토폴로지, K3s 런타임 계약, addon 경계, Ansible 부트스트랩에서 Argo CD 정상 상태로 넘어가는 핸드오프를 설명합니다.
상위 수준 클러스터 맵은 클러스터 개요를, ingress와 DNS는 네트워킹 개요를 참고하세요.
소스 경로
| 경로 | 역할 |
|---|---|
lumie-infra/provision/ansible/group_vars/all.yml | K3s 버전, CIDR, 레지스트리 미러, master API 대상, kubeconfig 경로 |
lumie-infra/provision/ansible/group_vars/masters.yml | 서버 설치 플래그와 TLS SAN |
lumie-infra/provision/ansible/roles/k3s-master/tasks/main.yml | K3s 서버 설치, 토큰 생성, 레지스트리 미러, API 준비 상태 검사 |
lumie-infra/provision/ansible/roles/k3s-worker/tasks/main.yml | 워커 토큰 가져오기, join 흐름, 등록 검증 |
lumie-infra/provision/ansible/playbooks/fetch-kubeconfig.yml | 운영자용 퍼블릭/프라이빗 kubeconfig 내보내기 |
lumie-infra/platform/traefik-config/helmchartconfig.yaml | k3s 번들 Traefik addon 패치 |
lumie-infra/platform/coredns-config/daemonset.yaml | 클러스터 DNS 워크로드 형태 재정의 |
클러스터 계약
K3s 기본값은 Ansible group vars에서 옵니다.
# lumie-infra/provision/ansible/group_vars/all.yml
k3s_version: "v1.34.3+k3s1"
k3s_cluster_cidr: "10.42.0.0/16"
k3s_service_cidr: "10.43.0.0/16"
zot_mirror_host: "zot.lumie-infra.com"
zot_mirror_endpoint: "http://zot.zot.svc.cluster.local:5000"
k3s_master_private_ip: "10.0.0.241"
이 계약은 다음을 결정합니다.
- K3s 서버와 에이전트 버전 고정
- OCI 시큐리티 리스트와 워커 라우팅이 사용하는 Pod/Service CIDR
- 모든 노드의 containerd 레지스트리 미러 동작
- 모든 에이전트 롤아웃의 워커 join 대상
토폴로지
코드상 의도된 토폴로지는 두 OCI VCN에 걸친 서버 1대와 여러 에이전트입니다. 2026년 6월 14일에 확인한 라이브 클러스터는 다음과 같았습니다.
| 노드 | 역할 | 내부 IP | 버전 |
|---|---|---|---|
k3s-master | 제어 평면 | 10.0.0.241 | v1.34.3+k3s1 |
k3s-worker-2 | 워커 | 10.0.0.2 | v1.34.3+k3s1 |
k3s-worker-3 | 워커 | 10.1.0.148 | v1.34.3+k3s1 |
k3s-worker-4 | 워커 | 10.1.0.9 | v1.34.3+k3s1 |
이 표는 desired-state 스키마가 아니라 관측된 런타임 상태로 보세요. desired-state 스키마는 Terraform 노드 맵과 Ansible inventory builder입니다.
런타임 흐름
진입점과 퍼블릭 표면
| 표면 | 단일 출처 | 비고 |
|---|---|---|
| Kubernetes API | https://10.0.0.241:6443의 k3s-master | 워커는 프라이빗 주소로 조인 |
| 운영자 kubeconfig | playbooks/fetch-kubeconfig.yml | k3s-public.yaml, k3s-private.yaml, config 심볼릭 링크 내보내기 |
| 내장 Traefik addon | K3s addon + platform/traefik-config/helmchartconfig.yaml | kube-system의 활성 ingress 컨트롤러 |
| CoreDNS | k3s addon config + 저장소 관리 DaemonSet 재정의 | 노드마다 DNS pod 1개 |
| 컨테이너 레지스트리 미러 | /etc/rancher/k3s/registries.yaml | 인클러스터 Zot으로 가져오기 유도 |
K3s 설치 및 조인 동작
master role은 바이너리가 없을 때만 K3s를 설치하고, 서비스 시작 전에 레지스트리 미러 구성을 작성한 뒤 /var/lib/rancher/k3s/server/node-token과 로컬 API /healthz를 기다립니다.
워커는 Git에 정적 join 토큰을 두지 않습니다. 대신 다음 순서로 진행합니다.
- master에서 토큰을
slurp합니다. 10.0.0.241:6443이 TCP 연결을 수락할 때까지 기다립니다.K3S_URL과K3S_TOKEN으로k3s-agent를 설치합니다.- 노드가 등록될 때까지 master에서
kubectl get nodes를 폴링합니다.
이 토큰 흐름이 워커 롤아웃의 주된 멱등성 가드입니다. 토큰을 inventory에 복사해 두지 않고, 라이브 클러스터에서 직접 읽어오기 때문입니다.
애드온 경계
K3s는 몇몇 클러스터 서비스를 함께 제공하지만, Lumie는 그 일부를 재정의합니다.
- Traefik은 이 저장소에서 독립 Helm 릴리스로 설치되지 않습니다. 활성 오브젝트는
HelmChartConfig로 패치된 k3s addon입니다. - CoreDNS는 여전히 클러스터가 제공하는
kube-system/corednsConfigMap을 사용하지만, 워크로드 형태는 저장소가 관리하는 DaemonSet으로 대체됩니다. local-path-provisioner와metrics-server는 k3s가 관리하는 런타임 컴포넌트로 남아 있으며, 라이브 클러스터에는 보이지만lumie-infra아래에서 버전 관리되지는 않습니다.
운영 메모
- master와 워커 역할 모두
/etc/rancher/k3s/registries.yaml을 템플릿으로 생성하므로 containerd는 인클러스터 Zot 미러를 우선 사용합니다. 따라서 Zot 또는 Traefik 경로 장애가 노드 수준 이미지 가져오기 실패로 드러날 수 있습니다. - master role은 퍼블릭 IP와 프라이빗 IP를 모두 TLS SAN으로 추가하고,
fetch-kubeconfig.yml은 운영자 접근을 위해127.0.0.1을 각 주소로 바꿔 씁니다. - 워커 설치는 join 경쟁을 줄이고 장애를 한 번에 한 노드씩 격리하기 위해 계정 그룹별 직렬 처리됩니다.
계약 드리프트
검사한 두 소스는 활성 클러스터 동작과 다릅니다.
lumie-infra/provision/ansible/README.md는 여전히Traefik | Disabled라고 말하지만,masters.yml은 더 이상--disable traefik을 전달하지 않고,platform/traefik-config/helmchartconfig.yaml은 번들 addon을 패치하며, 라이브 클러스터에는kube-system에 실행 중인traefikpod가 있습니다.terraform.tfvars.example에는 아직worker-1이 포함되어 있지만, 2026년 6월 14일에 확인한 라이브 클러스터에는 없습니다.
Kubernetes 동작을 문서화하거나 디버깅할 때는 오래된 README 요약보다 설치된 role과 라이브 클러스터를 신뢰하세요.
장애 지점
| 장애 지점 | 동작 |
|---|---|
k3s_master_private_ip 드리프트 | 노드 SSH는 되더라도 워커 join이 멈춤 |
| Zot 미러 경로 비가용 | containerd가 미러를 우선하므로 클러스터 전체에서 이미지 가져오기 실패가 날 수 있음 |
| Traefik/CoreDNS addon 가정이 틀림 | 이를 완전한 독립 저장소 관리 설치로 가정하면 잘못된 매니페스트를 추적하게 될 수 있음 |
| kubeconfig 가져오기를 건너뜀 | 서버 로컬 파일의 127.0.0.1을 가리킨 채 로컬 kubectl 접근이 남게 됨 |
검증
kubectl get nodes -o wide
kubectl get pods -n kube-system
kubectl get helmchartconfig -n kube-system traefik -o yaml
rg -n "k3s_version|k3s_cluster_cidr|k3s_service_cidr|zot_mirror|tls-san" \
lumie-infra/provision/ansible/group_vars \
lumie-infra/provision/ansible/roles