13년차의 서버실

서버, 인프라, 홈랩 기술 블로그

[카테고리:] Kubernetes

  • [k8s] k3s vs MicroK8s: 2026년 9월 기준 경량 쿠버네티스 비교 분석 및 선택 가이드

    [k8s] k3s vs MicroK8s: 2026년 9월 기준 경량 쿠버네티스 비교 분석 및 선택 가이드

    목차

    경량 쿠버네티스, 왜 지금 이 선택이 중요한가요?

    홈랩에 쿠버네티스를 올리려고 처음 도전했을 때가 생각나네요. 풀스택 쿠버네티스를 라즈베리파이 클러스터에 올렸다가 메모리가 터져서 노드가 죽어버리는 경험을 했거든요. 그때 처음 알게 된 게 바로 경량 쿠버네티스(Lightweight Kubernetes)라는 개념이었습니다.

    요즘은 엣지 컴퓨팅, IoT, 홈랩 쿠버네티스, 로컬 개발 환경, 소규모 프로덕션 클러스터까지 쿠버네티스를 돌려야 하는 상황이 정말 많아졌죠. 그런데 풀 쿠버네티스를 그대로 올리기엔 리소스 부담이 큽니다. 그래서 여전히 많은 분들이 k3s vs MicroK8s라는 주제로 고민하세요.

    저도 실제로 두 가지를 모두 운영해봤습니다. 홈랩 서버에서는 k3s를 오래 써왔고, 개발 팀 환경 구성이나 Ubuntu 기반 테스트 환경에서는 MicroK8s도 여러 번 써봤거든요. 이번 글에서는 2026년 9월 기준으로 바뀐 내용까지 반영해서, 어떤 상황에서 뭘 선택해야 하는지 현실적으로 정리해보겠습니다.

    k3s와 MicroK8s 경량 쿠버네티스 아키텍처 비교 다이어그램

    ▲ k3s와 MicroK8s의 전체 아키텍처 개요 — 두 경량 쿠버네티스의 구조적 차이를 한눈에 비교한 다이어그램

    k3s와 MicroK8s가 뭔지 먼저 짚고 가요

    k3s — 더 이상 40MB는 아니지만 여전히 가장 가벼운 축

    k3s는 Rancher Labs, 현재 SUSE에서 만든 경량 쿠버네티스 배포판입니다. 이름의 k3s는 k8s보다 더 가볍다는 의미에서 붙은 이름이고요. 요즘 기준으로는 100MB 안팎의 단일 바이너리라고 보는 게 더 정확합니다. 예전처럼 40MB짜리 쿠버네티스라고 딱 잘라 말하긴 어렵지만, 여전히 경량 쿠버네티스 대표 주자라는 건 변함이 없어요.

    주요 특징을 보면:

    • 단일 바이너리 중심 배포 — 설치가 정말 간단해요
    • 기본 스토리지 백엔드는 SQLite, 고가용성(HA)은 임베디드 etcd 또는 외부 DB 선택 가능
    • ARM 아키텍처 지원이 매우 좋아서 라즈베리파이 쿠버네티스 용도로 강함
    • containerd, Flannel, CoreDNS, Traefik, ServiceLB, local-path-provisioner 등을 기본 제공
    • 엣지 쿠버네티스, IoT, 에어갭 환경, 홈랩에 특히 잘 맞음
    • 2026년 9월 기준 최신 주요 릴리스 흐름은 Kubernetes 1.37 기반 k3s 1.37 계열까지 올라왔고, 1.34/1.35 계열도 패치 릴리스가 계속 제공되는 상황

    MicroK8s — Canonical이 만든 스냅 패키지 쿠버네티스

    MicroK8s는 Ubuntu를 만든 Canonical에서 개발한 경량 쿠버네티스입니다. 여전히 가장 큰 특징은 snap 패키지로 설치된다는 점이에요. Ubuntu 기반 서버나 개발용 워크스테이션에서는 정말 편합니다.

    • snap 패키지로 설치 — Ubuntu/Debian 계열에서 매우 간편
    • 애드온 시스템으로 기능 확장 — 필요한 것만 켜고 끄는 구조
    • 단일 노드부터 멀티노드, 고가용성 클러스터까지 지원
    • DNS, hostpath 스토리지, Ingress, MetalLB, GPU, observability 등 애드온 활성화가 쉬움
    • CNCF 인증 쿠버네티스 — 표준 호환성 높음
    • 업스트림 쿠버네티스 버전을 빠르게 따라가는 편이지만, 실제 설치 전에는 snap info microk8s로 채널별 최신 버전을 확인하는 게 안전함

    k3s vs MicroK8s 핵심 스펙 비교표

    말로만 설명하면 헷갈리니까 표로 정리해봤습니다. 특히 2026년 기준으로 바뀐 부분은 MicroK8s의 대시보드 제거, Ingress 애드온의 Traefik 전환, Gateway API 중요도 상승입니다.

    항목 k3s MicroK8s
    개발사 SUSE (원 개발: Rancher Labs) Canonical
    설치 방식 curl 스크립트 / 단일 바이너리 snap 패키지
    최소 메모리 약 512MB 수준부터 시작 가능 약 540MB 이상 권장
    기본 스토리지 백엔드 SQLite / 임베디드 etcd / 외부 DB dqlite 기반 HA 데이터스토어
    기본 컨테이너 런타임 containerd containerd
    기본 Ingress Traefik 포함 없음. microk8s enable ingress로 활성화, 최신 계열은 Traefik 기반
    Gateway API k3s 1.37부터 Gateway API CRD 번들 제공 Ingress 애드온과 Traefik 구성에서 Gateway API 흐름이 중요해짐
    ARM 지원 매우 강함 지원
    멀티노드 클러스터 비교적 단순 지원, HA 기본 지원 구조
    애드온 시스템 내장 컴포넌트 + Helm Chart 패턴 microk8s enable 명령어
    주요 사용 환경 엣지, IoT, 홈랩, 경량 프로덕션 개발 환경, Ubuntu 기반 서버, 빠른 테스트랩
    CNCF 인증 지원 지원

    포인트: 메모리 차이보다 더 중요한 건 운영 모델입니다. k3s는 최대한 작고 단순하게, MicroK8s는 Ubuntu 생태계에서 빠르게 확장 가능하게 쪽에 더 가깝습니다.

    실전 설치 및 구성 — 직접 해봤습니다

    k3s와 MicroK8s 터미널 설치 과정 단계별 화면

    ▲ k3s와 MicroK8s 실제 설치 과정 — 터미널에서 진행되는 단계별 설치 명령어 실행 화면

    k3s 설치 — 진짜 이렇게 쉬울 수가

    # k3s 서버 설치
curl -sfL https://get.k3s.io | sh -

# 설치 확인
sudo k3s kubectl get nodes

# 노드 토큰 확인
sudo cat /var/lib/rancher/k3s/server/node-token

    워커 노드 추가

    curl -sfL https://get.k3s.io | K3S_URL=https://마스터IP:6443 K3S_TOKEN=서버토큰값 sh -

    kubeconfig 설정

    mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
chmod 600 ~/.kube/config
sed -i 's/127.0.0.1/마스터서버IP/g' ~/.kube/config
kubectl get nodes

    주의: kubeconfig 권한이 너무 넓으면 kubectl이 경고를 냅니다. chmod 600 ~/.kube/config까지 같이 해두는 게 깔끔해요.

    k3s 추가 설정 — Traefik 비활성화 또는 버전 고정

    # Traefik 없이 설치
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable traefik" sh -

# 특정 버전 지정 설치 예시. 실제 최신 패치는 릴리스 노트 확인 권장
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.37.0+k3s1" sh -

    k3s 고가용성(HA) 시작점

    # 첫 서버를 embedded etcd 기반 HA 초기 노드로 시작
curl -sfL https://get.k3s.io | sh -s - server --cluster-init

# 이후 추가 서버 조인
curl -sfL https://get.k3s.io | K3S_URL=https://첫서버IP:6443 K3S_TOKEN=서버토큰값 sh -s - server

    MicroK8s 설치 — Ubuntu라면 더 편해요

    # 설치 전 채널 확인
snap info microk8s

# snap으로 MicroK8s 설치. 운영 환경은 버전 채널을 명시하는 편이 안전합니다.
sudo snap install microk8s --classic --channel=1.36/stable

sudo usermod -a -G microk8s $USER
mkdir -p ~/.kube
sudo chown -f -R $USER ~/.kube
newgrp microk8s

microk8s status --wait-ready
microk8s kubectl get nodes

    MicroK8s 핵심 애드온 활성화

    microk8s enable dns
microk8s enable hostpath-storage
microk8s enable ingress
microk8s enable metallb:192.168.1.200-192.168.1.220
microk8s enable dns hostpath-storage ingress

    예전 글이나 오래된 튜토리얼에는 microk8s enable dashboard가 자주 나오는데요. MicroK8s 1.36부터 dashboard 애드온과 dashboard-proxy 명령은 제거됐습니다. 웹 UI가 필요하다면 Lens, Headlamp, Argo CD, Rancher 같은 별도 도구를 검토하는 쪽이 현실적입니다.

    MicroK8s kubectl 별칭 설정

    alias kubectl='microk8s kubectl'
alias k='microk8s kubectl'
microk8s config > ~/.kube/microk8s-config
export KUBECONFIG=~/.kube/config:~/.kube/microk8s-config

    MicroK8s 멀티노드 클러스터 구성

    microk8s add-node
microk8s join 마스터IP:25000/토큰값/해시값
microk8s join 마스터IP:25000/토큰값/해시값 --worker
microk8s kubectl get nodes

    실제 삽질 포인트와 트러블슈팅

    k3s 트러블슈팅

    문제 1: 방화벽 때문에 워커 노드가 조인이 안 돼요

    sudo ufw allow 6443/tcp
sudo ufw allow 10250/tcp
sudo ufw allow 8472/udp
sudo ufw allow 51820/udp
sudo k3s kubectl get nodes -o wide
sudo journalctl -u k3s -f

    문제 2: SQLite에서 HA로 커지기 시작할 때

    단일 노드면 SQLite도 충분합니다. 다만 처음부터 고가용성 운영을 할 거면 embedded etcd로 시작하는 게 가장 깔끔해요. 중간에 뒤늦게 구조를 바꾸면 생각보다 손이 많이 갑니다.

    curl -sfL https://get.k3s.io | sh -s - server --cluster-init

    문제 3: 이미지 pull 속도가 너무 느려요

    # /etc/rancher/k3s/registries.yaml
mirrors:
  docker.io:
    endpoint:
      - "https://mirror.gcr.io"
  "내부레지스트리주소:5000":
    endpoint:
      - "http://내부레지스트리주소:5000"
configs:
  "내부레지스트리주소:5000":
    auth:
      username: admin
      password: password
    tls:
      insecure_skip_verify: true
    sudo systemctl restart k3s

    MicroK8s 트러블슈팅

    문제 1: snap/커널 조합 때문에 설치가 꼬여요

    uname -r
microk8s inspect
sudo snap refresh microk8s --channel=1.36/stable

    문제 2: 예전 튜토리얼대로 dashboard 접근이 안 돼요

    이건 사용자가 잘못한 게 아니라, 최신 버전에서 절차가 바뀐 것입니다. MicroK8s 1.36부터는 dashboard 애드온과 microk8s dashboard-proxy가 제거됐어요. 따라서 예전 방식으로는 당연히 안 됩니다.

    문제 3: snap 자동 업데이트로 버전이 올라가버려요

    sudo snap refresh --hold microk8s
sudo snap refresh --hold=forever microk8s
snap refresh --time

    MicroK8s는 같은 채널 안에서는 자동 refresh가 일어날 수 있습니다. 운영 환경이라면 채널 고정, hold 정책, 업그레이드 테스트 순서를 미리 정해두는 게 좋습니다.

    실제 운영 결과 및 성능 비교

    k3s와 MicroK8s 리소스 사용량 성능 모니터링 대시보드 비교

    ▲ k3s와 MicroK8s 리소스 사용량 모니터링 대시보드 — CPU, 메모리 사용량 실시간 비교 차트

    동일한 스펙의 VM 두 대에 각각 설치해서 비교해봤습니다. 수치는 환경과 활성화한 애드온에 따라 달라질 수 있으니 참고용으로 봐주세요.

    유휴 상태(Idle) 리소스 사용량

    측정 항목 k3s MicroK8s
    메모리 사용량 약 450MB~600MB 약 550MB~750MB
    CPU 사용률 유휴 시 0.5% 이하인 경우가 많음 유휴 시 1~2% 수준인 경우가 많음
    준비 시간 약 15~30초 약 30~60초
    디스크 사용량 상대적으로 작음 snap 포함 시 더 큼

    k3s가 전반적으로 더 가벼운 편이긴 한데, 이 차이는 정말 빡빡한 ARM 보드나 소형 엣지 장비에서 더 크게 느껴집니다. 일반적인 VM이나 미니 PC 수준에선 완전히 다른 세상 정도는 아니에요.

    Pod 배포 속도 테스트

    time kubectl create deployment nginx-test --image=nginx --replicas=5
kubectl rollout status deployment/nginx-test

    결론적으로 두 환경 모두 배포 체감은 비슷했습니다. 실제 차이는 컨테이너 이미지 pull, CNI 초기화, 스토리지 프로비저너 상태 같은 주변 요소에서 더 많이 납니다.

    어떤 걸 선택해야 할까요? — 상황별 가이드

    k3s를 선택해야 하는 경우

    • 라즈베리파이, 임베디드 시스템 등 ARM 기반 엣지 환경
    • 멀티노드 클러스터를 간단하게 구성하고 싶을 때
    • Ubuntu 외 다른 Linux 배포판을 사용할 때
    • 프로덕션 엣지 배포가 목적일 때
    • 인터넷 연결이 불안정하거나 에어갭 설치가 필요한 환경
    • 홈랩 쿠버네티스를 최대한 가볍게 운영하고 싶을 때
    • Gateway API CRD 번들 제공 같은 최신 k3s 1.37 흐름을 활용하고 싶을 때

    MicroK8s를 선택해야 하는 경우

    • Ubuntu 기반 개발 환경에서 빠르게 쿠버네티스 셋업
    • 애드온 시스템으로 간편하게 기능 확장하고 싶을 때
    • Canonical/Ubuntu 생태계를 이미 사용 중일 때
    • 개발자가 로컬에서 표준 쿠버네티스 환경이 필요할 때
    • GPU 워크로드나 observability 애드온을 빨리 붙여보고 싶을 때
    • snap 기반 설치와 채널 관리 모델이 조직 운영 방식에 잘 맞을 때

    둘 다 아닌 경우도 있어요

    개발 환경에서 쿠버네티스가 필요한데 설치도 귀찮고 리소스도 아끼고 싶다면, kind(Kubernetes in Docker)나 minikube도 충분히 좋은 선택입니다. 특히 CI 파이프라인이나 일회성 테스트 환경은 kind가 더 깔끔할 때가 많아요.

    자주 묻는 질문 (FAQ)

    Q. k3s와 MicroK8s 중 어느 게 더 프로덕션에 적합한가요?

    엣지, 홈랩, 소규모 서비스 운영처럼 가볍고 단순한 운영이 중요하면 k3s 쪽을 먼저 봅니다. Ubuntu 표준 환경, snap 기반 배포, 애드온 중심 운영이 편한 팀이라면 MicroK8s도 충분히 좋은 선택입니다.

    Q. 라즈베리파이에는 뭘 써야 하나요?

    개인적으로는 k3s를 먼저 추천합니다. ARM 지원, 설치 단순성, 리소스 사용량 면에서 라즈베리파이 쿠버네티스와 잘 맞습니다.

    Q. 기존 kubectl 명령어를 그대로 쓸 수 있나요?

    네. k3s는 k3s kubectl 또는 일반 kubectl을 사용할 수 있고, MicroK8s는 microk8s kubectl을 쓰거나 alias/kubeconfig를 설정하면 됩니다.

    Q. 풀 쿠버네티스에서 k3s/MicroK8s로 마이그레이션이 쉬운가요?

    기본 리소스는 대부분 비슷하지만, Ingress Controller, StorageClass, LoadBalancer, CNI, CSI 드라이버 차이에서 손볼 일이 생깁니다. 특히 2026년 기준으로는 Ingress와 Gateway API 전략을 함께 검토하는 게 좋습니다.

    2026년 9월 기준, 꼭 알아야 할 최신 변화

    1. MicroK8s는 이제 대시보드 기본 경로를 기대하면 안 됩니다

    MicroK8s 1.36부터 dashboard 관련 기능이 제거됐습니다. 예전처럼 microk8s enable dashboard와 microk8s dashboard-proxy를 기대하면 막힙니다. 운영 가시성이 필요하다면 Headlamp, Lens, Grafana, Argo CD UI 같은 대안을 선택하는 편이 낫습니다.

    2. Ingress와 Traefik, Gateway API 변화는 생각보다 영향이 큽니다

    MicroK8s의 ingress 애드온은 최신 계열에서 Traefik 중심으로 바뀌었고, k3s도 기본 Ingress Controller로 Traefik을 포함합니다. 여기에 k3s 1.37부터는 Gateway API CRD가 번들로 제공되기 시작했습니다. 앞으로 새 클러스터를 만든다면 단순히 Ingress만 볼 게 아니라 Kubernetes Gateway API, Traefik Gateway, Cilium Gateway API 같은 선택지도 함께 비교하는 게 좋습니다.

    3. 홈랩 쿠버네티스와 엣지 쿠버네티스 운영 포인트

    홈랩에서는 설치보다 백업, 인증서, 스토리지, 자동 업데이트 관리가 더 중요합니다. k3s라면 etcd/SQLite 백업과 /etc/rancher/k3s 설정 보관, MicroK8s라면 snap refresh 정책과 애드온 상태 점검을 운영 체크리스트에 넣어두세요.

    4. Kubernetes 1.37 시대의 새 키워드: Gateway API와 워크로드 스케줄링

    Kubernetes 1.37에서는 Gateway API, 동적 리소스 할당(DRA), 워크로드 인식 스케줄링 같은 흐름이 더 중요해졌습니다. k3s와 MicroK8s를 비교할 때도 이제는 단순히 가볍냐 무겁냐만 볼 게 아니라, 엣지 AI 워크로드, GPU 워크로드, 로컬 쿠버네티스 개발환경, GitOps 운영까지 함께 고려하는 쪽이 더 현실적입니다.

    마무리 — 그래서 저는 뭘 쓰냐고요?

    제 기준은 단순합니다. 홈랩, 라즈베리파이, 엣지 장비, 작고 오래 가는 클러스터라면 k3s를 고릅니다. Ubuntu 개발 장비에서 빠르게 켜고 끄는 테스트 클러스터, 애드온을 손쉽게 붙여보는 실험 환경이라면 MicroK8s를 고릅니다.

    둘 다 좋은 도구입니다. 다만 운영 방식이 다릅니다. k3s는 작고 조용하게 오래 가는 쪽에 가깝고, MicroK8s는 Ubuntu 생태계 안에서 빠르게 실험하고 확장하는 쪽에 가깝습니다. 결국 답은 내 환경이 어떤 실패를 견뎌야 하는지에 달려 있습니다.

    🔄 마지막 업데이트: 2026년 09월

  • [k8s] k3s 최신 버전: 경량 쿠버네티스 설치 및 운영 실전 가이드

    [k8s] k3s 최신 버전: 경량 쿠버네티스 설치 및 운영 실전 가이드

    목차

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

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

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

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

    k3s 경량 쿠버네티스 아키텍처 다이어그램 — 서버 노드와 에이전트 노드 구성

    ▲ 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 비교

    항목 k8s (일반) k3s 최신 버전
    최소 RAM 2GB (마스터 기준) 512MB (서버 기준)
    바이너리 크기 여러 컴포넌트 (수 GB) 단일 바이너리 (~100MB)
    설치 시간 30분 이상 1~2분
    기본 데이터스토어 etcd SQLite (소규모), 임베디드 etcd (HA)
    Ingress 기본 포함 ❌ ✅ Traefik
    적합한 환경 대규모 프로덕션 엣지, IoT, 홈랩, 소규모 프로덕션

    저는 처음에 “이렇게 줄이면 뭔가 빠진 거 아닐까?” 걱정했는데, 실제로 써보니까 일반적인 워크로드(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 멀티 노드 클러스터 설치 완료 후 kubectl get nodes 결과 화면

    ▲ 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 위에 올려서 쓰고 있는데, 이건 다음 글에서 자세히 다룰 예정입니다.

    k3s 클러스터 Grafana 모니터링 대시보드 — CPU, 메모리, 파드 상태 시각화

    ▲ 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 vs 쿠버네티스(k8s) 비교 인포그래픽 — 리소스, 설치 복잡도, 사용 환경 비교

    ▲ 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 클러스터를 하나의 대시보드로 관리하는 게 정말 편하거든요. 이전 글에서 다뤘던 홈랩 네트워크 구성과 함께 보시면 더 도움이 될 겁니다.

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