k3s 최신 버전, 왜 지금 써야 할까요?

쿠버네티스(Kubernetes)를 공부하거나 실무에 적용하려고 마음먹었는데, 막상 설치하려니 서버 사양부터 막히셨던 경험 있으신가요? 저도 처음엔 그랬거든요. 풀스택 쿠버네티스 클러스터를 집에서 돌리려면 메모리만 수십 GB가 필요하고, 설정 파일은 또 얼마나 복잡한지… 솔직히 포기하고 싶었던 적이 한두 번이 아닙니다.

그러다가 만난 게 k3s 최신 버전이었어요. Rancher Labs(현 SUSE)에서 만든 경량 쿠버네티스인데, 처음 써봤을 때 진짜 “이게 뭔가?” 싶을 정도로 설치가 간단했습니다. 명령어 하나로 끝나거든요. 13년 동안 인프라 엔지니어로 일하면서 이렇게 설치가 간단한 쿠버네티스 배포판은 처음 봤어요.

이 글에서는 제가 홈랩에서 직접 k3s를 설치하고 운영하면서 겪었던 경험을 바탕으로, 설치부터 실제 운영까지 실전 가이드를 공유해 드리겠습니다. 엣지 컴퓨팅(Edge Computing)이나 소규모 클러스터를 구성하려는 분들께 특히 도움이 될 거예요.

▲ k3s의 전체 아키텍처 — 서버(마스터)와 에이전트(워커) 노드 구성 개요. 일반 쿠버네티스보다 훨씬 단순한 구조가 특징입니다.

k3s 최신 버전이란 무엇인가요? 경량 쿠버네티스 핵심 개념

쉽게 말해서, k3s는 “다이어트한 쿠버네티스”

쿠버네티스(Kubernetes, 이하 k8s)는 컨테이너 오케스트레이션(Container Orchestration, 컨테이너를 자동으로 배포·관리·확장하는 기술)의 표준이죠. 근데 이 k8s, 무겁습니다. 기본 설치만 해도 최소 2GB RAM이 필요하고, etcd, API 서버, 스케줄러 등 컴포넌트가 여러 개 따로 돌아가요.

k3s는 이 k8s를 단일 바이너리(Single Binary)로 패키징해서 약 100MB 이하로 줄인 경량 쿠버네티스입니다. 핵심 기능은 그대로 유지하면서, 사용 빈도가 낮은 기능들을 과감히 제거했거든요.

k3s 최신 버전이 제거하거나 교체한 것들

• etcd → SQLite 또는 임베디드 etcd로 교체 (고가용성 구성 시 etcd 사용 가능)
• 클라우드 프로바이더 플러그인 제거 (AWS, GCP 등 특정 클라우드 의존성 제거)
• 알파(Alpha) 기능 제거
• 기본 CNI(Container Network Interface)로 Flannel 내장
• 기본 로드밸런서로 ServiceLB(구 Klipper) 내장
• Helm Controller, Traefik Ingress 기본 포함

k3s 최신 버전 vs 일반 k8s 비교

저는 처음에 “이렇게 줄이면 뭔가 빠진 거 아닐까?” 걱정했는데, 실제로 써보니까 일반적인 워크로드(Workload, 실제 운영 중인 애플리케이션)에서는 전혀 차이를 못 느꼈어요. CNCF(Cloud Native Computing Foundation) 인증도 받은 정식 쿠버네티스 배포판이거든요.

k3s 최신 버전 설치 실전 가이드

사전 준비 — 환경 확인

제 홈랩 환경을 기준으로 설명할게요. 라즈베리파이 4B 3대와 우분투 서버 1대를 혼용해서 클러스터를 구성했습니다.

• OS: Ubuntu 22.04 LTS / Raspberry Pi OS (64bit)
• 최소 사양: 1 vCPU, 512MB RAM (서버 노드는 1GB 이상 권장)
• 네트워크: 노드 간 통신 가능한 동일 네트워크 또는 VPN
• 포트: 6443(API), 8472(Flannel VXLAN), 10250(Kubelet) 열려 있어야 함

1단계 — 서버(마스터) 노드 설치

k3s 최신 버전 설치는 정말 간단합니다. 공식 설치 스크립트 하나로 끝나요. 처음 이걸 보고 “이게 다야?” 했던 기억이 나네요 ㅎㅎ

# k3s 최신 버전 서버 노드 설치
curl -sfL https://get.k3s.io | sh -

# 설치 확인
sudo systemctl status k3s

# 노드 상태 확인
sudo kubectl get nodes

설치가 완료되면 /etc/rancher/k3s/k3s.yaml에 kubeconfig 파일이 생성됩니다. 이게 클러스터에 접근하기 위한 인증 정보예요.

# kubeconfig를 기본 위치로 복사 (로컬에서 kubectl 사용)
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config

# 에이전트 노드 연결을 위한 토큰 확인
sudo cat /var/lib/rancher/k3s/server/node-token

2단계 — 에이전트(워커) 노드 추가

워커 노드(Worker Node, 실제 컨테이너가 실행되는 노드)를 추가하는 것도 간단해요. 아까 확인한 토큰과 서버 IP만 있으면 됩니다.

# 에이전트 노드에서 실행 (K3S_URL과 K3S_TOKEN을 실제 값으로 교체)
curl -sfL https://get.k3s.io | K3S_URL=https://서버IP:6443 K3S_TOKEN=토큰값 sh -

# 서버 노드에서 노드 추가 확인
sudo kubectl get nodes -o wide

▲ k3s 최신 버전으로 멀티 노드 클러스터 구성 완료 — 서버 1대 + 에이전트 2대로 구성된 소규모 클러스터. kubectl get nodes 명령어로 확인한 상태 화면.

3단계 — 고가용성(HA) 구성 (선택사항)

단일 서버 노드는 장애가 발생하면 클러스터 전체가 영향을 받아요. 프로덕션 환경이라면 HA(High Availability, 고가용성) 구성을 추천합니다. k3s 최신 버전에서는 임베디드 etcd를 사용하는 방식이 가장 간편해요.

# 첫 번째 서버 노드 — 임베디드 etcd로 클러스터 초기화
curl -sfL https://get.k3s.io | sh -s - server \
  --cluster-init \
  --tls-san 로드밸런서IP또는도메인

# 두 번째, 세 번째 서버 노드 — 클러스터에 합류
curl -sfL https://get.k3s.io | sh -s - server \
  --server https://첫번째서버IP:6443 \
  --token 토큰값 \
  --tls-san 로드밸런서IP또는도메인

💡 팁: HA 구성에는 서버 노드가 홀수(3개 또는 5개)여야 etcd 리더 선출이 제대로 됩니다. 이건 k3s만의 특성이 아니라 etcd 자체의 특성이에요.

4단계 — 실제 애플리케이션 배포 테스트

클러스터가 잘 돌아가는지 간단한 nginx를 배포해서 확인해 봅시다.

# nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-test
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx-test
  template:
    metadata:
      labels:
        app: nginx-test
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-test-svc
  namespace: default
spec:
  selector:
    app: nginx-test
  ports:
  - port: 80
    targetPort: 80
  type: LoadBalancer

# 배포 적용
kubectl apply -f nginx-deployment.yaml

# 파드(Pod) 상태 확인
kubectl get pods -o wide

# 서비스 상태 확인 (EXTERNAL-IP 할당 확인)
kubectl get svc nginx-test-svc

k3s에는 ServiceLB가 내장되어 있어서, 베어메탈(Bare Metal, 클라우드가 아닌 실제 물리 서버) 환경에서도 LoadBalancer 타입 서비스에 외부 IP가 할당되더라고요. 이게 진짜 편하거든요. 일반 k8s에서는 MetalLB 같은 걸 따로 설치해야 하니까요.

⚠️ 삽질 모음 — 제가 겪은 실전 트러블슈팅

문제 1: 라즈베리파이에서 cgroup 오류

라즈베리파이에 k3s를 처음 설치했을 때 파드가 계속 Pending(대기) 상태에서 안 올라오는 거예요. 로그를 보니까 cgroup(Control Group, 프로세스 자원 제한 기능) 관련 오류가 뜨더라고요. 이거 때문에 두 시간 삽질했습니다 ㅎㅎ

# /boot/cmdline.txt 또는 /boot/firmware/cmdline.txt 파일 수정
# 파일 끝에 다음 내용 추가 (줄바꿈 없이 한 줄로)
sudo nano /boot/firmware/cmdline.txt

# 추가할 내용:
cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1

# 재부팅 후 k3s 재설치
sudo reboot

문제 2: 방화벽(UFW)이 노드 간 통신을 막는 경우

우분투 서버에 UFW(Uncomplicated Firewall)가 활성화되어 있으면 노드 간 통신이 막힐 수 있어요. 에이전트 노드가 Ready 상태가 안 될 때 의심해볼 부분입니다.

# k3s 관련 포트 허용
sudo ufw allow 6443/tcp    # API 서버
sudo ufw allow 8472/udp    # Flannel VXLAN
sudo ufw allow 10250/tcp   # Kubelet
sudo ufw allow 51820/udp   # WireGuard (암호화 사용 시)

# 또는 내부 네트워크 전체 허용 (홈랩 환경)
sudo ufw allow from 192.168.0.0/24

문제 3: Traefik Ingress 인증서 관련 이슈

k3s에 기본 포함된 Traefik(트레픽, 리버스 프록시 겸 인그레스 컨트롤러)을 쓸 때 HTTPS 설정에서 막히는 분들이 많더라고요. cert-manager(인증서 자동 관리 도구)를 함께 설치하면 훨씬 편하더라고요.

# cert-manager 설치
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

# 설치 확인
kubectl get pods -n cert-manager

k3s 최신 버전 운영 시 알아두면 좋은 것들

k3s 최신 버전 업그레이드하기

k3s 최신 버전으로 업그레이드하는 방법은 생각보다 간단해요. 공식에서 제공하는 system-upgrade-controller를 사용하면 자동화도 가능하거든요.

# 수동 업그레이드 (가장 간단한 방법)
curl -sfL https://get.k3s.io | sh -

# 특정 버전으로 설치/업그레이드
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.31.0+k3s1 sh -

유용한 k3s 설정 옵션들

k3s 서버 시작 시 다양한 옵션을 줄 수 있어요. /etc/rancher/k3s/config.yaml 파일로 관리하는 게 훨씬 편합니다.

# /etc/rancher/k3s/config.yaml (서버 노드)
write-kubeconfig-mode: "0644"
tls-san:
  - "192.168.1.100"
  - "k3s.mylab.local"
disable:
  - traefik        # 기본 Traefik 비활성화 (다른 Ingress 사용 시)
node-label:
  - "role=master"
cluster-cidr: "10.42.0.0/16"   # 파드 네트워크 대역
service-cidr: "10.43.0.0/16"   # 서비스 네트워크 대역

Helm Chart 배포 자동화

k3s는 HelmChart CRD(Custom Resource Definition, 사용자 정의 리소스)를 기본 제공해요. 이걸 쓰면 YAML 파일 하나로 Helm Chart 배포를 자동화할 수 있거든요. 홈랩에서 진짜 유용하게 쓰고 있습니다.

# prometheus 자동 배포 예시
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: prometheus
  namespace: kube-system
spec:
  repo: https://prometheus-community.github.io/helm-charts
  chart: kube-prometheus-stack
  targetNamespace: monitoring
  createNamespace: true
  valuesContent: |-
    grafana:
      enabled: true
      adminPassword: "your-secure-password"

✅ 설치 결과 검증 및 모니터링

드디어 클러스터가 다 올라왔을 때 “됐다!” 하는 그 기분… 직접 겪어보셔야 알아요 🎉

클러스터 상태를 한눈에 확인하는 방법들을 정리해 드릴게요.

# 전체 클러스터 상태 확인
kubectl get nodes -o wide
kubectl get pods -A
kubectl top nodes   # metrics-server 설치 필요

# k3s 서비스 상태
sudo systemctl status k3s

# k3s 로그 확인
sudo journalctl -u k3s -f

# 클러스터 정보
kubectl cluster-info

좀 더 시각적인 대시보드를 원하신다면 Rancher나 Lens(쿠버네티스 GUI 클라이언트)를 추천해요. k3s 클러스터를 등록하면 웹 UI로 모든 리소스를 관리할 수 있거든요. 저는 홈랩에서 Rancher를 k3s 위에 올려서 쓰고 있는데, 이건 다음 글에서 자세히 다룰 예정입니다.

▲ Grafana + Prometheus로 구성한 k3s 클러스터 모니터링 대시보드 — CPU, 메모리, 파드 상태를 실시간으로 확인할 수 있습니다.

자주 묻는 질문 (FAQ)

Q. k3s는 프로덕션 환경에서 사용 가능한가요?

네, 충분히 가능합니다. CNCF 인증 쿠버네티스 배포판이고, 실제로 많은 기업에서 엣지 컴퓨팅이나 소규모 프로덕션 환경에서 k3s를 사용하고 있어요. 다만 대규모 엔터프라이즈 환경에서는 일반 k8s나 EKS/GKE 같은 관리형 서비스가 더 적합할 수 있습니다.

Q. k3s 최신 버전은 어디서 확인하나요?

GitHub 릴리즈 페이지(github.com/k3s-io/k3s/releases)에서 확인할 수 있어요. 기본 설치 스크립트는 항상 최신 stable 버전을 설치합니다.

Q. k3s와 k3d의 차이는 뭔가요?

k3d는 k3s를 Docker 컨테이너 안에서 실행하는 도구예요. 로컬 개발 환경에서 빠르게 클러스터를 만들고 지울 때 유용합니다. k3s는 실제 VM이나 물리 서버에 설치하는 거고요.

Q. 라즈베리파이에서 k3s가 잘 돌아가나요?

네! 라즈베리파이 4B(4GB 이상) 기준으로 서버 노드로도 충분히 동작합니다. 다만 앞서 언급한 cgroup 설정은 꼭 해주셔야 해요. ARM64 아키텍처를 공식 지원하거든요.

▲ k3s와 일반 쿠버네티스(k8s) 비교 요약 — 리소스 사용량, 설치 복잡도, 적합한 사용 환경을 한눈에 비교한 인포그래픽.

마무리 — k3s 최신 버전 정리 및 다음 단계

k3s 최신 버전, 어떠셨나요? 생각보다 훨씬 간단하죠? 저도 처음 설치했을 때 “이게 진짜 쿠버네티스가 맞나?” 싶을 정도였거든요. 그런데 막상 써보면 표준 kubectl 명령어가 다 먹히고, Helm Chart도 그대로 쓸 수 있어서 실용적입니다.

오늘 배운 것들을 정리하면:

• ✅ k3s는 단일 바이너리로 배포되는 경량 쿠버네티스 — 512MB RAM으로도 동작
• ✅ k3s 설치는 curl 명령어 하나로 완료 — 정말 1~2분이면 끝
• ✅ Traefik Ingress, ServiceLB, Helm Controller 기본 내장
• ✅ 라즈베리파이, 엣지 디바이스, 홈랩에 최적
• ✅ HA 구성도 임베디드 etcd로 간단하게 가능
• ⚠️ 라즈베리파이는 cgroup 설정 필수
• ⚠️ 방화벽 포트 설정 꼭 확인

다음 글에서는 k3s 위에 Rancher를 올려서 멀티 클러스터를 관리하는 방법을 다룰 예정이에요. 홈랩에서 여러 k3s 클러스터를 하나의 대시보드로 관리하는 게 정말 편하거든요. 이전 글에서 다뤘던 홈랩 네트워크 구성과 함께 보시면 더 도움이 될 겁니다.

혹시 설치하다가 막히는 부분이 있으면 댓글로 남겨주세요. 제가 겪어본 삽질이 꽤 많아서 도움이 될 수도 있거든요 😄