Skip to main content

Kubernetes (K3s)

Lumie 플랫폼은 K3s를 사용하여 경량화된 Kubernetes 클러스터를 운영합니다. K3s는 Oracle Cloud Infrastructure(OCI)의 ARM64 인스턴스에서 실행되며, 멀티 테넌시 환경을 지원합니다.

클러스터 아키텍처​

노드 구성​

클러스터는 두 개의 OCI 계정에 걸쳐 구성되어 있으며, VCN 피어링을 통해 연결됩니다:

0214 계정 (마스터 계정)​

  • 마스터 노드: k3s-master

    • 컨트롤 플레인 컴포넌트
    • etcd 데이터베이스
    • ArgoCD 설치
    • Private IP: 10.0.0.241

  • 워커 노드: k3s-worker-2

    • 애플리케이션 워크로드
    • 모니터링 스택
    • MinIO 스토리지
    • Traefik svclb (포트 80/443)
    • worker-1은 비용 최적화로 2026-04 제외됨

0213 계정 (워커 계정)​

  • 워커 노드: k3s-worker-3, k3s-worker-4
    • 추가 워커 노드
    • VCN 피어링을 통해 마스터와 연결
    • MinIO 스토리지
    • Traefik svclb (포트 80/443)

네트워크 구성​

K3s 구성​

버전 및 설정​

  • K3s 버전: v1.34.3+k3s1
  • CNI: Flannel (기본값)
  • Ingress: Traefik 활성화 (K3s 기본 내장)
  • Storage: local-path-provisioner

마스터 노드 설정​

# provision/ansible/group_vars/masters.yml
k3s_server_args:
  - "--write-kubeconfig-mode 644"
  - "--tls-san {{ ansible_host }}"      # 공용 IP
  - "--tls-san {{ private_ip }}"        # 프라이빗 IP
  - "--cluster-cidr {{ k3s_cluster_cidr }}"
  - "--service-cidr {{ k3s_service_cidr }}"

--disable traefik 옵션이 없으므로 K3s 내장 Traefik이 활성화됩니다. Traefik의 svclb DaemonSet은 마스터 노드에서 제외되어 443 포트 충돌을 방지합니다.

워커 노드 연결​

워커 노드는 마스터의 Private IP를 통해 연결됩니다:

# 0214 계정 워커 (같은 VCN)
K3S_URL="https://10.0.0.241:6443"

# 0213 계정 워커 (VCN 피어링)
K3S_URL="https://10.0.0.241:6443"

클러스터 접근​

Kubeconfig 설정​

Ansible을 통해 kubeconfig를 로컬로 가져올 수 있습니다:

# kubeconfig 가져오기
ansible-playbook -i inventory/terraform_inventory.py playbooks/fetch-kubeconfig.yml

# 환경 변수 설정
export KUBECONFIG=provision/ansible/kubeconfig/config

# 클러스터 확인
kubectl get nodes

SSH 접근​

# 마스터 노드 접근
ssh ubuntu@<master-public-ip>

# 마스터에서 kubectl 사용
sudo kubectl get nodes
sudo kubectl get pods -A

네임스페이스 구조​

각 서비스는 독립적인 네임스페이스에서 실행됩니다:

네임스페이스용도관리 방식
lumie-backendSpring Boot 모노리스 백엔드GitOps
lumie-frontendNext.js 프론트엔드GitOps
lumie-workerPython 워커 서비스 (grading, report, audio, analysis)GitOps
lumie-dbPostgreSQL (CNPG) + PgBouncerGitOps
lumie-cacheRedis SentinelGitOps
lumie-eventRabbitMQGitOps
argocdArgoCD 배포GitOps
tekton-pipelinesTekton CI/CDGitOps
minioMinIO 오브젝트 스토리지GitOps
vaultVault 시크릿 관리GitOps
teleportTeleport 제로 트러스트 접근GitOps
keycloakOIDC 인증 제공자GitOps
cert-manager인증서 관리GitOps
kube-systemK3s 시스템 컴포넌트 (Traefik 포함)K3s 관리
observabilityPrometheus, Grafana, Loki, Tempo 등GitOps

스토리지 구성​

블록 볼륨​

각 워커 노드는 MinIO용 50GB 블록 볼륨을 가집니다:

# 마운트 포인트
/mnt/minio-data

# 파일시스템
ext4

# 라벨
minio-<node-name>

스토리지 클래스​

  • local-path: 기본 스토리지 클래스
    • 로컬 디스크 사용
    • 개발 및 비중요 데이터용

일반적인 운영 작업​

클러스터 상태 확인​

# 노드 상태
kubectl get nodes -o wide

# 모든 네임스페이스의 파드
kubectl get pods -A

# 시스템 파드 상태 (Traefik 포함)
kubectl get pods -n kube-system

애플리케이션 상태 확인​

# 특정 네임스페이스
kubectl get all -n <namespace>

# 파드 로그 확인
kubectl logs -n <namespace> <pod-name>

# 파드 상세 정보
kubectl describe pod -n <namespace> <pod-name>

ArgoCD 애플리케이션 관리​

대부분의 애플리케이션은 ArgoCD를 통해 관리됩니다:

# ArgoCD 애플리케이션 확인
kubectl get applications -n argocd

# 애플리케이션 강제 동기화
kubectl patch application -n argocd <app-name> \
  -p '{"metadata": {"annotations": {"argocd.argoproj.io/refresh": "hard"}}}' \
  --type merge

네트워킹​

보안 그룹 규칙​

클러스터는 다음 포트를 사용합니다:

포트프로토콜용도
22TCPSSH
80TCPHTTP (Traefik, 워커 노드)
443TCPHTTPS (Traefik 워커 노드 / Teleport NodePort 30443 → worker-3/4)
6443TCPK3s API Server
10250TCPKubelet API
8472UDPFlannel VXLAN
51820UDPWireGuard

트래픽 라우팅​

두 개의 OCI NLB를 통해 외부 트래픽을 라우팅합니다:

인터넷 → k3s-nlb (168.107.42.253) → Traefik (svclb, 워커 노드) → Service → Pod
인터넷 → teleport-nlb (158.180.89.154) → NodePort 30443 (worker-3/4) → Teleport Pod

문제 해결​

파드 시작 실패​

# 파드 이벤트 확인
kubectl describe pod -n <namespace> <pod-name>

# 로그 확인
kubectl logs -n <namespace> <pod-name>

# 이전 컨테이너 로그 (크래시된 경우)
kubectl logs -n <namespace> <pod-name> --previous

리소스 문제​

# 노드 리소스 사용량
kubectl top nodes

# 파드 리소스 사용량
kubectl top pods -A

# 리소스 할당량 확인
kubectl describe quota -A

네트워크 연결 문제​

# 서비스 확인
kubectl get svc -A

# 엔드포인트 확인
kubectl get endpoints -A

# 네트워크 디버깅 파드 실행
kubectl run -it --rm debug --image=nicolaka/netshoot --restart=Never -- /bin/bash

VCN 피어링 문제​

# 0213 계정 워커에서 마스터 연결 테스트
telnet 10.0.0.241 6443

# 라우팅 테이블 확인 (OCI 콘솔)
# 피어링 게이트웨이 상태 확인

모니터링​

클러스터 메트릭​

Prometheus를 통해 다음 메트릭을 수집합니다:

  • 노드 리소스 사용량
  • 파드 상태 및 리소스
  • 네트워크 트래픽
  • 스토리지 사용량

로그 수집​

Loki를 통해 모든 파드 로그를 중앙 집중식으로 수집합니다.

알림​

Alertmanager를 통해 다음 상황에 대한 알림을 설정합니다:

  • 노드 다운
  • 파드 크래시
  • 리소스 부족
  • 네트워크 문제

보안​

네트워크 정책​

Kyverno를 통해 네트워크 정책을 자동으로 적용합니다:

  • 네임스페이스 간 격리
  • 외부 트래픽 제한
  • 서비스 메시 보안

시크릿 관리​

Vault를 통해 모든 시크릿을 중앙 관리합니다:

  • 데이터베이스 자격 증명
  • API 키
  • TLS 인증서

관련 문서​