13년차의 서버실

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

[태그:] k3s

  • [k8s] MicroK8s 벤치마크: K3s와 엣지 환경 성능 비교 [실전 가이드]

    [k8s] MicroK8s 벤치마크: K3s와 엣지 환경 성능 비교 [실전 가이드]

    목차

    [인프라] MicroK8s 벤치마크: K3s와 엣지 환경 리소스 사용량 비교

    홈랩을 굴리다 보면 결국 한 번은 부딪히는 주제가 있습니다. 바로 MicroK8s 벤치마크를 어떻게 봐야 하느냐는 점이거든요. 저도 ARM 서버를 만지면서 처음엔 “둘 다 경량 쿠버네티스인데 뭐가 그렇게 다르지?” 싶었는데, 실제로 써보니까 꽤 차이가 있더라고요. 특히 엣지 컴퓨팅이나 소형 ARM 보드, 미니 PC처럼 자원이 넉넉하지 않은 환경에서는 이런 차이가 더 크게 체감됩니다.

    이번 글에서는 MicroK8s와 K3s 성능 비교를 단순한 스펙 나열이 아니라, 실제로 어떤 항목을 벤치마크해야 의미가 있는지 중심으로 정리해보겠습니다. 제가 직접 홈랩에서 테스트할 때 썼던 방식, 삽질했던 포인트, 그리고 해석할 때 조심해야 할 점까지 같이 적어볼게요.

    MicroK8s 벤치마크를 위한 엣지 환경 ARM 서버 아키텍처 다이어그램

    엣지 환경에서 경량 쿠버네티스를 비교하는 전체 구성을 한눈에 보여주는 이미지입니다.

    1. 왜 엣지 환경에서는 MicroK8s 벤치마크가 중요할까

    데이터센터에서는 CPU랑 메모리를 조금 더 쓰더라도 관리 편의성이 좋으면 넘어가는 경우가 많습니다. 근데 엣지에서는 얘기가 달라집니다. 1~2GB 메모리 차이, 디스크 I/O 초기화 시간, 컨트롤 플레인(control plane, 클러스터 제어 영역) 기동 속도 같은 게 꽤 민감하게 다가오거든요.

    쉽게 말해, 같은 Kubernetes(쿠버네티스, 컨테이너 오케스트레이션 플랫폼) 계열이라도 무엇을 기본으로 포함하느냐, 어떤 런타임을 묶어 배포하느냐, 초기 설치와 운영 자동화가 어디까지 되어 있느냐에 따라 체감 리소스 사용량이 달라집니다. 그래서 MicroK8s 벤치마크를 볼 때는 숫자 하나보다도 “어떤 조건에서 잰 숫자인가?”를 먼저 보셔야 합니다.

    2. MicroK8s와 K3s, 쉽게 말해 뭐가 다를까

    저도 처음엔 둘 다 그냥 작은 경량 쿠버네티스 배포판 정도로 이해했었는데요, 실제로는 운영 철학이 꽤 다릅니다.

    항목 MicroK8s K3s
    배포 성격 Canonical에서 제공하는 경량 쿠버네티스 배포판 Rancher 진영에서 시작된 경량 쿠버네티스 배포판
    설치 방식 snap 기반 설치가 대표적 단일 바이너리 중심 설치 경험이 간단한 편
    체감 특징 애드온(add-on, 부가 기능) 관리가 편함 가볍고 빠르게 올리기 좋음
    엣지 적합성 기능 일체감이 좋음 최소 자원 환경에서 선호되는 경우가 많음

    여기서 중요한 포인트! 경량 쿠버네티스라고 해서 무조건 가장 적은 메모리만 쓰는 제품을 고르면 끝은 아닙니다. 예를 들어 Ingress(인그레스, 외부 트래픽 진입점), DNS, StorageClass(스토리지 클래스, 동적 볼륨 정책) 같은 기본 기능을 나중에 붙이기 시작하면, 처음의 “가벼움”이 생각보다 금방 상쇄되거든요.

    3. MicroK8s 벤치마크는 무엇을 비교해야 의미가 있을까

    MicroK8s 벤치마크라고 검색하면 CPU, 메모리 그래프 하나 딱 보여주는 자료가 많은데요, 실무에서는 그걸로 판단하기 어렵습니다. 제가 실제로 비교할 때는 아래 항목을 기준으로 잡았습니다.

    • Idle resource usage(유휴 리소스 사용량): 아무 워크로드 없을 때 CPU와 메모리 사용량
    • Cold start time(콜드 스타트 시간): 설치 후 API 응답 가능 상태까지 걸리는 시간
    • Pod scheduling latency(파드 스케줄링 지연): 테스트 파드가 실제 Running 상태가 되기까지의 시간
    • Add-on overhead(부가 기능 오버헤드): DNS, Ingress, Metrics 추가 후 증가 폭
    • Disk footprint(디스크 점유): 설치 후 데이터 디렉터리 증가량

    사실 이 다섯 개만 잡아도 꽤 감이 옵니다. 특히 ARM 서버에서는 디스크 성능이 병목이 되는 경우가 많아서, 메모리만 보면 놓치는 게 많더라고요.

    4. 제가 홈랩에서 잡은 테스트 조건

    벤치마크는 조건 통제가 핵심입니다. 같은 하드웨어, 같은 OS 계열, 같은 컨테이너 이미지, 같은 측정 횟수로 맞춰야 비교가 그나마 공정해집니다. 저는 아래처럼 맞춰서 보는 편입니다.

    1. 테스트 대상 노드는 동일한 ARM 기반 장비 또는 동일 사양 미니 PC로 구성합니다.
    2. 운영체제는 같은 Ubuntu 계열로 맞춥니다.
    3. 백그라운드 서비스와 자동 업데이트는 측정 전 최대한 정리합니다.
    4. MicroK8s와 K3s는 각각 단일 노드로 먼저 비교합니다.
    5. 기본 상태와 add-on 활성화 상태를 따로 측정합니다.
    6. 각 측정은 3회 이상 반복해서 편차를 확인합니다.

    이 부분을 안 맞추면 진짜 헷갈립니다. 저도 처음엔 결과가 들쭉날쭉해서 한참 헤맸는데, 알고 보니 한쪽은 메트릭 수집기가 떠 있었고 다른 쪽은 아니더라고요. 삽질 좀 했습니다 ㅎㅎ

    5. 실전 구현: MicroK8s와 K3s 벤치마크 준비

    5-1. MicroK8s 설치와 기본 확인

    sudo snap install microk8s --classic
sudo usermod -a -G microk8s $USER
newgrp microk8s
microk8s status --wait-ready
microk8s kubectl get nodes -o wide

    MicroK8s는 snap 기반이라 설치 경험이 꽤 일관적입니다. 대신 snapd 상태나 채널(channel, 배포 트랙)에 따라 초기 준비 시간이 다르게 느껴질 수 있습니다.

    5-2. K3s 설치와 기본 확인

    curl -sfL https://get.k3s.io | sh -
sudo kubectl get nodes -o wide
sudo systemctl status k3s --no-pager

    K3s는 설치가 정말 간단합니다. 처음 써보면 “이렇게 빨리 올라온다고?” 싶은 느낌이 있어요. 엣지 환경에서 자주 언급되는 이유가 괜히 있는 게 아니더라고요.

    MicroK8s 벤치마크와 K3s 성능 비교를 위한 단일 노드 설치 상태 이미지

    단일 노드 환경에서 두 배포판의 설치 직후 상태를 비교하는 장면을 보여주는 이미지입니다.

    5-3. 공통 워크로드 배포

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-bench
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx-bench
  template:
    metadata:
      labels:
        app: nginx-bench
    spec:
      containers:
      - name: nginx
        image: nginx:stable
        ports:
        - containerPort: 80
---
    kubectl apply -f nginx-bench.yaml
kubectl get pods -w

    여기서는 복잡한 앱보다 단순한 워크로드가 낫습니다. 이유는 비교 대상을 경량 쿠버네티스 배포판 자체로 최대한 좁혀야 하기 때문입니다.

    5-4. 유휴 리소스와 파드 상태 측정

    free -h
vmstat 1 5
ps aux --sort=-%mem | head
kubectl get pods -A
kubectl top nodes
kubectl top pods -A

    Metrics Server(메트릭 서버, 리소스 수집 컴포넌트)가 없는 상태라면 kubectl top이 바로 안 될 수 있습니다. 이때는 OS 레벨 지표와 함께 보셔야 합니다.

    6. ⚠️ 실제로 겪었던 문제와 트러블슈팅

    6-1. 애드온 차이 때문에 공정 비교가 안 되는 문제

    이게 제일 흔합니다. MicroK8s는 add-on 활성화가 쉽고, K3s는 기본 구성이 상대적으로 간결한 편이라 시작점이 다를 수 있거든요. 그래서 기본 설치 상태와 필수 기능 포함 상태를 따로 비교해야 합니다.

    microk8s enable dns ingress metrics-server
kubectl get pods -A

    혹시 이런 경험 있으신가요? “왜 MicroK8s가 더 무겁지?” 하고 봤더니 사실 기능이 더 많이 켜져 있었던 겁니다.

    6-2. ARM 서버에서 스토리지 지연 때문에 체감이 달라지는 문제

    특히 SD 카드나 느린 eMMC 기반 장비에서는 API 응답보다 이미지 풀(image pull, 컨테이너 이미지 다운로드)과 파일 시스템 동기화가 더 큰 변수였습니다. 그래서 이미지를 미리 받아둔 상태와 처음 내려받는 상태를 분리해서 봐야 해요.

    6-3. 첫 부팅과 재부팅 후 상태가 다른 문제

    처음엔 이게 뭔가 싶었는데, 재부팅 후 서비스 재기동 순서와 캐시 영향으로 결과가 다르게 나오더라고요. 그래서 가능하면 아래처럼 측정 구간을 분리하는 게 좋습니다.

    • 설치 직후 측정
    • 재부팅 후 안정화 뒤 측정
    • 워크로드 배포 후 측정

    7. 검증과 결과 해석: 숫자보다 패턴을 보셔야 합니다

    제가 여러 번 비교해보면서 느낀 패턴은 이렇습니다. K3s는 초기 설치와 기동이 간결하게 느껴지고, MicroK8s는 기능 통합과 관리 편의성이 좋다는 점입니다. 그리고 K3s 성능 비교 자료를 볼 때 자주 나오는 “더 가볍다”는 평은, 대체로 최소 구성 기준에서 이해하면 맞습니다.

    반대로 실서비스에 가까운 구성으로 DNS, Ingress, 모니터링 관련 요소를 하나씩 붙이기 시작하면, 단순 메모리 숫자만으로는 승부가 잘 안 나기도 합니다. 여기서 중요한 건 운영 편의성 대비 리소스 비용입니다. CPU 몇 퍼센트, 메모리 몇백 MB보다도 내가 관리하면서 덜 고생하는 쪽이 전체 비용은 더 낮을 수 있거든요.

    MicroK8s 벤치마크 결과를 보여주는 CPU 메모리 대시보드 이미지

    유휴 상태와 워크로드 배포 후 상태를 비교하는 벤치마크 대시보드 이미지입니다.

    비교 관점 MicroK8s에서 보기 좋은 점 K3s에서 보기 좋은 점
    초기 셋업 애드온 중심 운영이 편함 빠르고 단순하게 시작 가능
    리소스 민감 환경 기능 포함 시 구성 일관성 확보 최소 구성에서 부담이 적은 편
    실험/홈랩 여러 기능을 켜보며 배우기 좋음 가볍게 여러 노드 실험하기 좋음
    운영 판단 기준 기능 통합성 경량성과 단순성

    즉, MicroK8s 벤치마크 결과를 해석할 때는 “기본 상태 비교인지”, “실제 운영 기능 포함 비교인지”를 꼭 구분하셔야 합니다.

    8. 어떤 환경에 무엇을 고르면 좋을까

    • 초소형 엣지 노드나 아주 타이트한 리소스 환경이면 K3s 쪽이 출발이 편할 가능성이 큽니다.
    • 학습, 홈랩, 기능 실험을 자주 하신다면 MicroK8s의 add-on 경험이 꽤 편합니다.
    • ARM 서버를 여러 대 운영하면서 자동화까지 보실 거라면 설치 이후 운영 스크립트와 모니터링 방식까지 같이 검토하셔야 합니다.

    저는 개인적으로 “최소 자원 + 빠른 프로비저닝”이 우선이면 K3s를 먼저 보고, “기능 포함 상태에서 일관된 운영 경험”이 중요하면 MicroK8s를 먼저 봅니다. 둘 중 하나가 절대적으로 우월하다기보다, 우선순위가 다르다고 보는 게 맞더라고요.

    9. 정리와 다음 단계

    정리해보면, MicroK8s 벤치마크는 단순히 누가 더 메모리를 덜 먹느냐로 끝나지 않습니다. 엣지 환경에서는 설치 방식, 애드온 구조, 스토리지 특성, 재부팅 후 복구 속도, 그리고 운영 중 손이 얼마나 가는지가 다 같이 중요합니다. 제가 직접 해보니 숫자 하나보다 패턴이 더 중요했고, 특히 비교 조건을 통일하는 게 절반이더라고요.

    다음 글에서는 실제 홈랩 기준으로 Prometheus(프로메테우스, 메트릭 수집 시스템)와 Grafana(그라파나, 시각화 도구)를 붙여서 MicroK8s와 K3s의 장기 모니터링 방법도 다뤄볼 예정입니다. 이전 글에서 다뤘던 홈랩 네트워크 설계 내용과도 연결해서 보시면 더 이해가 쉬우실 겁니다.

    MicroK8s 벤치마크와 K3s 선택 기준을 요약한 인포그래픽

    어떤 조건에서 어떤 배포판이 더 잘 맞는지 한 장으로 정리한 요약 이미지입니다.

    자주 묻는 질문

    Q1. MicroK8s와 K3s 중 뭐가 무조건 더 빠른가요?

    무조건이라고 말하긴 어렵습니다. 최소 구성에서는 K3s가 가볍게 느껴지는 경우가 많지만, 운영 기능을 붙인 뒤에는 비교 조건에 따라 달라집니다.

    Q2. 엣지 컴퓨팅에서는 무엇을 먼저 봐야 하나요?

    CPU보다도 메모리, 디스크 I/O, 재기동 안정성을 먼저 보시는 걸 권장합니다. 특히 느린 저장장치에서는 체감 차이가 크게 납니다.

    Q3. 홈랩 입문자는 무엇으로 시작하면 좋을까요?

    기능을 빨리 배우고 싶으면 MicroK8s, 아주 가볍게 여러 노드를 올려보고 싶으면 K3s가 편할 수 있습니다.

  • [k8s] Rancher 2.x에서 차세대로 마이그레이션: 실제 경험과 주요 변경점

    [k8s] Rancher 2.x에서 차세대로 마이그레이션: 실제 경험과 주요 변경점

    안녕하세요, 13년차 서버실 지킴이입니다. 오늘은 많은 분들이 고민하고 계실 법한 주제, 바로 Rancher 2.x 환경을 차세대 쿠버네티스 관리 아키텍처로 전환하는 경험에 대해 이야기해볼게요. 제목에는 ‘Rancher 3.x’라는 표현을 썼지만, 사실 직접적인 ‘Rancher 3.x’라는 버전이 명확하게 출시된 것은 아닙니다. 대신, Rancher를 활용한 쿠버네티스 관리 방식이 점차 진화하면서, 기존 2.x 시절의 방식과는 크게 달라진 미래 지향적인 아키텍처로의 전환 과정을 ‘3.x 마이그레이션’이라는 개념으로 풀어보려고 해요. 즉, 단순히 버전을 올리는 것을 넘어, 더 효율적이고 안정적인 쿠버네티스 운영을 위한 근본적인 변화를 고민하는 시간이라고 보시면 되겠습니다.

    저도 홈랩에서부터 시작해서 프로덕션 환경까지 다양한 규모의 쿠버네티스 클러스터를 Rancher 2.x로 관리해왔어요. 처음에는 하나의 Rancher 서버로 모든 클러스터를 중앙에서 관리하는 방식이 정말 편하더라고요. 하지만 클러스터의 수가 늘어나고, 요구사항이 복잡해지면서 중앙 집중형 관리의 한계를 느끼게 됐습니다. 특히, Rancher 서버 자체의 안정성이나 업그레이드 부담, 그리고 GitOps(깃옵스)와 같은 최신 트렌드를 통합하는 데 대한 고민이 많았거든요. 그래서 ‘이제는 좀 더 분산되고 선언적인 방식으로 가야 하지 않을까?’ 하는 생각을 하게 됐습니다. 이런 고민을 하고 계신 분들이라면 오늘 제 이야기가 작은 팁이라도 될 수 있을 겁니다. 제가 직접 삽질해가며 얻은 경험들을 솔직하게 공유해볼게요!

    개념 설명: Rancher 2.x와 차세대 아키텍처의 차이

    먼저, 우리가 이야기하는 Rancher 2.x는 보통 RKE1(Rancher Kubernetes Engine 1) 기반의 쿠버네티스 클러스터들을 Rancher Management Server(랜처 관리 서버)가 중앙에서 프로비저닝하고 관리하는 형태를 의미합니다. 웹 UI를 통해 클러스터를 생성하고, 워크로드를 배포하며, 모니터링까지 한곳에서 할 수 있었죠. 정말 편리하고 직관적입니다. 하지만 단점도 명확해요.

    • 중앙 집중형 의존성: Rancher Management Server에 장애가 발생하면 모든 하위 클러스터 관리에 문제가 생길 수 있습니다.
    • 관리 복잡성 증가: 클러스터가 많아질수록 관리 서버 자체의 부담도 커집니다.
    • GitOps 통합의 어려움: UI 기반의 작업이 많아 GitOps 파이프라인과 완벽하게 통합하기 쉽지 않은 부분이 있었습니다.

    그렇다면 여기서 말하는 ‘차세대 아키텍처’ 혹은 ‘3.x스러운’ 접근 방식은 뭘까요? 저는 주로 RKE2(Rancher Kubernetes Engine 2)나 K3s(케이쓰리s)와 같은 경량화되거나 보안이 강화된 쿠버네티스 배포판을 활용하고, GitOps 원칙을 적극적으로 도입하여 선언적(Declarative)으로 클러스터와 애플리케이션을 관리하는 방식을 의미한다고 봐요. 이제 더 이상 Rancher Management Server가 클러스터의 모든 것을 직접 제어하기보다는, 클러스터 자체의 견고함과 Git을 통한 선언적 관리에 초점을 맞추는 거죠. Rancher는 이런 클러스터들을 통합적으로 보여주고 관리하는 ‘플랫폼’으로서의 역할에 더 집중하게 됩니다.

    Rancher 2.x 중앙 집중형 관리와 차세대 분산형 GitOps 아키텍처 비교 다이어그램

    Rancher 2.x의 중앙 집중형 관리 방식과 차세대 분산형 GitOps 아키텍처의 주요 차이점을 시각적으로 보여주는 다이어그램입니다.

    실전 구현: 차세대 클러스터 환경 구축 전략

    기존 Rancher 2.x 환경을 ‘마이그레이션’하는 것은 단순히 버전을 올리는 것이 아니라, 새로운 클러스터를 구축하고 워크로드를 이전하는 과정에 가깝습니다. 제가 홈랩에서 여러 번 시도해본 결과, 크게 두 가지 접근 방식이 있더라고요.

    1. 새로운 RKE2/K3s 클러스터 프로비저닝

    먼저, 기존 Rancher 2.x 관리 서버에서 새로운 RKE2나 K3s 클러스터를 프로비저닝하는 방법을 소개할게요. Rancher 2.6 버전부터는 RKE2/K3s 클러스터 생성을 공식적으로 지원해서 훨씬 수월해졌습니다.

    1. Rancher UI 접속: 기존 Rancher Management Server의 웹 UI에 접속합니다.
    2. 클러스터 생성 메뉴 진입: ‘클러스터’ 탭에서 ‘클러스터 생성’ 버튼을 클릭합니다.
    3. RKE2/K3s 선택: ‘Rancher Kubernetes Engine 2 (RKE2)’ 또는 ‘K3s’를 선택합니다. 저는 보안과 성능을 고려해 RKE2를 선호하는 편입니다.
    4. 노드 구성 및 옵션 설정: 컨트롤 플레인(Control Plane), etcd, 워커(Worker) 노드를 구성하고 필요한 네트워크, CNI(Container Network Interface, 컨테이너 네트워크 인터페이스) (예: Canal, Calico 등) 옵션을 설정합니다. 이때, 클러스터의 고가용성(High Availability, HA)을 위해 컨트롤 플레인 노드를 최소 3개 이상으로 구성하는 것이 중요합니다.
    5. 클러스터 생성: 모든 설정을 마치고 클러스터를 생성하면, Rancher가 백그라운드에서 노드에 에이전트를 설치하고 RKE2/K3s를 배포합니다.

    다음은 RKE2 클러스터를 생성할 때 필요한 기본적인 설정 예시입니다.

    # 클러스터 생성 시 RKE2/K3s 설정 예시 (Rancher UI에서 구성)
kubernetes_version: v1.27.x-rke2r1 # 원하는 RKE2 버전 선택
cni: canal # CNI 플러그인 선택 (calico, cilium 등)
cloud_provider: 
  name: aws # 클라우드 환경에 맞춰 설정 (baremetal, azure, vsphere 등)
agent_options:
  node_taints:
    - "CriticalAddonsOnly=true:NoExecute"
  labels:
    - "node-role.kubernetes.io/control-plane=true"
    - "node-role.kubernetes.io/etcd=true"
# 노드 추가는 Rancher UI에서 직접 진행하거나, Machine Group을 통해 자동화 가능

    이렇게 새 클러스터를 만들고 나면, 이제 기존 워크로드들을 새로운 클러스터로 이전할 준비가 된 겁니다. 이게 생각보다 쉽지 않아요. 애플리케이션 의존성부터 데이터 마이그레이션까지 고려할 게 많거든요. 제가 초반에 이걸 간과해서 밤샘 삽질을 좀 했습니다. 😅

    Rancher UI에서 RKE2 클러스터를 생성하는 화면 예시

    Rancher UI를 통해 새로운 RKE2 클러스터를 생성하는 화면 예시입니다. 여기서 다양한 옵션을 설정할 수 있습니다.

    2. 워크로드 및 데이터 마이그레이션

    가장 중요한 단계입니다. 워크로드 마이그레이션은 서비스 중단 시간을 최소화하는 방향으로 계획해야 해요. 몇 가지 팁을 드리자면:

    • 상태 없는(Stateless) 애플리케이션 먼저: 웹 서버, API 게이트웨이 등 상태를 저장하지 않는 애플리케이션부터 이전하여 위험을 줄입니다. Helm(헬름)이나 GitOps 툴(예: Argo CD, Flux CD)을 활용하면 배포를 선언적으로 관리하고 쉽게 이전할 수 있어요.
    • 상태 있는(Stateful) 애플리케이션: 데이터베이스와 같은 상태 있는 애플리케이션은 velero(벨레로)와 같은 백업 및 복구 툴을 사용하거나, 클라우드 제공업체의 볼륨 스냅샷 기능을 활용하여 데이터를 이전합니다. 이 과정에서 네트워크 지연(Latency)이나 데이터 정합성(Data Consistency)에 문제가 없는지 꼼꼼히 확인해야 해요.
    • 네트워크 설정: Ingress(인그레스, 외부 트래픽 진입점) 컨트롤러, Service(서비스) 타입, ExternalDNS(외부 DNS) 설정 등을 새 클러스터에 맞게 재구성해야 합니다. 특히 DNS 레코드를 변경할 때는 TTL(Time-To-Live, 캐시 유지 시간)을 짧게 설정하여 롤백에 대비하는 것이 좋습니다.
    # Argo CD를 이용한 GitOps 배포 예시
# 새 클러스터에 Argo CD 설치 후, Git 리포지토리 연결

# 1. Argo CD 설치 (새 클러스터에)
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# 2. Argo CD CLI 설치 및 초기 비밀번호 확인
# (생략)

# 3. 애플리케이션 정의 (예: my-app.yaml)
# applications/my-app.yaml 파일 생성
# apiVersion: argoproj.io/v1alpha1
# kind: Application
# metadata:
#   name: my-webapp
#   namespace: argocd
# spec:
#   project: default
#   source:
#     repoURL: https://github.com/my-org/my-app-configs.git # 애플리케이션 설정이 있는 Git 레포지토리
#     targetRevision: HEAD
#     path: dev # Git 레포지토리 내 경로
#   destination:
#     server: https://kubernetes.default.svc
#     namespace: my-webapp-prod # 배포할 네임스페이스
#   syncPolicy:
#     automated:
#       prune: true
#       selfHeal: true

# 4. Argo CD에 애플리케이션 등록
argocd app create my-webapp --repo https://github.com/my-org/my-app-configs.git --path dev --dest-server https://kubernetes.default.svc --dest-namespace my-webapp-prod

    이런 GitOps 툴을 활용하면, 기존 클러스터에서 사용하던 매니페스트(Manifest) 파일들을 Git 레포지토리에 올리고, 새 클러스터에 Argo CD를 설치하여 동기화하는 방식으로 쉽게 워크로드를 이전할 수 있어요. 코드로 인프라를 관리하는(Infrastructure as Code, IaC) 경험은 정말 혁신적입니다!

    ⚠️ 주의사항 및 트러블슈팅: 삽질 경험 공유

    제가 이 ‘차세대 전환’을 하면서 겪었던 몇 가지 삽질과 해결책들을 공유해볼게요.

    1. RKE1과 RKE2/K3s의 설정 차이: RKE1은 cluster.yml 파일을 기반으로 클러스터를 구성했지만, RKE2/K3s는 /etc/rancher/rke2/config.yaml (또는 k3s) 파일을 사용하거나 Helm 차트 등을 통해 더 세분화된 설정을 합니다. 기존 RKE1의 커스텀 설정(예: 추가 컨테이너 런타임 옵션, CNI 플러그인 설정)을 그대로 옮기려다 호환성 문제로 고생 좀 했어요. 새로운 배포판의 문서(Documentation)를 꼼꼼히 확인하는 것이 정말 중요합니다.
    2. StorageClass(스토리지 클래스) 호환성: 기존 클러스터에서 사용하던 PersistentVolume(영구 볼륨)과 PersistentVolumeClaim(영구 볼륨 클레임)은 StorageClass에 따라 다르게 동작할 수 있습니다. 특히 클라우드 환경이 변경되거나 스토리지 솔루션이 달라지면, 새로운 StorageClass를 정의하고 기존 PV/PVC를 마이그레이션해야 해요. 저는 홈랩에서 Longhorn(롱혼)을 사용하는데, 새 클러스터에 Longhorn을 재설치하고 데이터를 옮기는 과정에서 네트워크 설정 문제로 볼륨이 마운트되지 않아 애먹었습니다. 😅
    3. Cilium(실리움) CNI 도입 시 주의사항: 최근 Cilium이 성능과 보안 면에서 각광받고 있어서 저도 도입을 고려했는데, 기존 CNI(예: Canal)에서 Cilium으로 변경할 때는 네트워크 정책(Network Policy)과의 호환성, kube-proxy(쿠베 프록시) 없이 동작하는 모드(Direct Routing) 설정 등 고려할 사항이 많아요. 잘못하면 클러스터 내부 통신이 마비될 수 있으니 충분한 테스트 환경에서 검증해야 합니다.
    4. Rancher Management Server의 역할 변화: 기존에는 Rancher 서버가 모든 것을 다 해주는 느낌이었다면, 이제는 ‘관측성(Observability)’과 ‘정책 관리(Policy Management)’, 그리고 ‘클러스터 수명 주기 관리(Cluster Lifecycle Management)’에 더 집중하게 됩니다. 즉, 클러스터 내부의 복잡한 운영은 GitOps 툴과 같은 다른 도구들에게 맡기고, Rancher는 그 위에서 통합된 뷰를 제공하는 역할로 전환되는 거죠. 이 역할을 이해하지 못하면 ‘왜 Rancher가 예전처럼 클러스터 설정을 다 해주지 않지?’ 하고 헤맬 수 있습니다.

    검증 및 결과: 안정적인 차세대 환경 확인

    모든 워크로드 마이그레이션이 완료되었다면, 새로운 클러스터가 제대로 동작하는지 꼼꼼히 검증해야 합니다. 다음은 제가 주로 확인하는 항목들입니다.

    • 애플리케이션 정상 동작 확인: 모든 서비스의 엔드포인트에 접속하여 기능이 정상적으로 동작하는지 확인합니다. 특히 로깅(Logging)과 모니터링(Monitoring) 시스템이 제대로 연동되는지 확인하는 것이 중요해요.
    • 리소스 사용량 모니터링: Grafana(그라파나), Prometheus(프로메테우스) 등의 툴을 통해 CPU, 메모리, 네트워크, 디스크 I/O 등 클러스터 리소스 사용량을 면밀히 모니터링합니다. 기존 클러스터와 비교하여 비정상적인 패턴이 없는지 확인해야 합니다.
    • 클러스터 컴포넌트 상태: kubectl get pods -A 명령어로 모든 네임스페이스의 파드(Pod) 상태를 확인하고, kubectl get nodes로 노드 상태를 확인하여 문제가 없는지 점검합니다.
    • 데이터 정합성 검증: 상태 있는 애플리케이션의 경우, 이전된 데이터가 정확한지, 쓰기/읽기 작업이 문제없이 이루어지는지 반드시 확인해야 합니다.

    이 모든 검증을 마치고 나면, 드디어 새로운 차세대 Rancher 환경이 안정적으로 운영되는 것을 확인할 수 있어요. 이 뿌듯함이란! 🎉

    새롭게 마이그레이션된 Rancher 환경의 클러스터 대시보드

    새롭게 마이그레이션된 Rancher 환경에서 클러스터의 전반적인 상태를 보여주는 대시보드 화면입니다.

    마무리: 배운 점과 다음 단계

    Rancher 2.x에서 차세대 쿠버네티스 관리 환경으로의 전환은 단순히 소프트웨어 버전을 올리는 작업이 아니었습니다. 이는 클러스터 아키텍처, 운영 방식, 그리고 인프라 엔지니어의 역할에 대한 근본적인 재정의 과정이라고 생각해요. 저도 이 과정을 거치면서 많은 것을 배우고 삽질도 정말 많이 했습니다. 하지만 그 덕분에 GitOps의 중요성, RKE2/K3s의 장점, 그리고 Rancher가 나아가야 할 방향에 대해 더 깊이 이해하게 되었죠.

    Rancher 환경 전환 시 고려해야 할 핵심 사항 요약 인포그래픽

    Rancher 환경 전환 시 고려해야 할 핵심 사항들을 요약한 인포그래픽입니다.

    이번 마이그레이션을 통해 얻은 주요 교훈은 다음과 같습니다.

    • 계획의 중요성: 충분한 사전 계획 없이는 성공적인 마이그레이션은 불가능해요. 의존성 파악, 백업/복구 전략, 롤백 계획 등 모든 것을 미리 준비해야 합니다.
    • GitOps의 힘: 선언적인 코드로 인프라와 애플리케이션을 관리하는 GitOps는 복잡한 마이그레이션을 훨씬 수월하게 만들고, 향후 운영의 안정성을 높여줍니다.
    • 문서화의 중요성: 모든 변경 사항과 결정 사항을 문서화하여 팀원들과 공유하고, 향후 트러블슈팅에 활용해야 합니다.

    이제 새로운 클러스터에서 더 안정적이고 효율적인 쿠버네티스 운영을 할 수 있게 되었어요. 다음 단계로는 클러스터의 보안 강화(Security Hardening), 자동화된 재해 복구(Automated Disaster Recovery) 시스템 구축, 그리고 멀티 클러스터 환경에서의 서비스 메시(Service Mesh) 도입 등을 고민해볼 예정입니다. 여러분도 혹시 비슷한 고민을 하고 계시다면, 주저하지 말고 새로운 아키텍처로의 전환을 시도해보세요. 물론 삽질은 필수겠지만, 그만큼 얻는 것도 많을 겁니다! 궁금한 점이 있다면 언제든 댓글 남겨주세요. 다음 포스팅에서 또 재미있는 이야기로 찾아뵙겠습니다!

  • [k8s] K3s/MicroK8s로 구축하는 경량 엣지 쿠버네티스: 실제 운영 사례 분석

    [k8s] K3s/MicroK8s로 구축하는 경량 엣지 쿠버네티스: 실제 운영 사례 분석

    안녕하세요, 13년차 서버실 지킴이입니다. 오늘도 제 홈랩 서버에서 굴러가는 작은 친구들 이야기를 좀 해볼까 합니다. 요즘 엣지 컴퓨팅(Edge Computing)에 대한 관심이 정말 뜨거우니까요? 클라우드의 강점을 작은 엣지 디바이스까지 끌어내려는 움직임이 활발합니다. 그런데 막상 작은 디바이스에 쿠버네티스(Kubernetes)를 올리려고 하면, 덩치 큰 녀석이라 부담스러울 때가 많았거든요.

    저도 처음엔 라즈베리 파이(Raspberry Pi) 같은 작은 보드 컴퓨터에 풀 스택 쿠버네티스를 올려보려다가 리소스 부족으로 꽤나 삽질을 했어요. 😅 그러다 발견한 보석 같은 친구들이 바로 K3s와 MicroK8s거든요. 이 경량 쿠버네티스 배포판들이 엣지 환경에서 얼마나 쓸모 있게 쓰일 수 있는지, 그리고 제가 직접 운영하면서 겪었던 경험담들을 공유해볼까 합니다. 저처럼 작은 디바이스에서 쿠버네티스를 돌려보고 싶으셨던 분들이라면 오늘 글이 좋은 가이드가 될 거예요!

    엣지 컴퓨팅 환경에서 경량 쿠버네티스 클러스터가 어떻게 구성되는지 보여주는 아키텍처 다이어그램

    이미지: 엣지 환경에서 경량 쿠버네티스 클러스터가 어떻게 구성되는지 보여주는 아키텍처 다이어그램입니다.

    K3s와 MicroK8s, 뭐가 다를까? (개념 설명 및 비교)

    경량 쿠버네티스라는 카테고리 안에 K3s와 MicroK8s가 대표주자인데, 이 둘은 각각 다른 접근 방식으로 ‘가벼움’을 추구해요. 핵심부터 쉽게 설명해 드릴게요.

    K3s: Rancher Labs의 선택

    K3s는 Rancher Labs에서 만든 경량 쿠버네티스 배포판이에요. ‘K8s’에서 숫자 8을 3으로 바꾼 건, 일반적인 쿠버네티스보다 절반도 안 되는 리소스로 동작한다는 의미를 담고 있더라고요. 💡 K3s의 가장 큰 특징은 단일 바이너리(Single Binary) 형태로 배포된다는 점이에요. 모든 핵심 컴포넌트(kube-apiserver, kube-controller-manager 등)가 하나의 파일에 쏙 들어있어서 설치가 정말 간편합니다. 게다가 SQLite를 기본 데이터베이스로 써서 외부 DB(데이터베이스) 없이도 잘 동작하거든요. 엣지 환경처럼 리소스가 제한적이거나 네트워크 연결이 불안정한 곳에 정말 안성맞춤이죠.

    MicroK8s: Canonical의 유연성

    MicroK8s는 Canonical(우분투를 만드는 회사)에서 만든 경량 쿠버네티스예요. K3s만큼 설치가 간단한 건 맞는데, 애드온(Add-ons) 시스템이 정말 강점이거든요. Ingress(인그레스, 외부 트래픽 진입점), DNS, Storage(스토리지) 같은 필수 기능들을 필요할 때마다 쉽게 켜고 끄는 식으로 활성화할 수 있어요. 스냅(Snap) 패키지로 배포되기 때문에 우분투(Ubuntu) 환경에서 특히 설치와 관리가 편리합니다. 저는 홈랩에서 우분투를 주로 쓰는데, MicroK8s는 정말 친숙하게 느껴지더라고요.

    간단한 비교 표

    두 솔루션의 특징을 한눈에 보기 위해 표로 정리해봤어요.

    특징 K3s MicroK8s
    개발사 Rancher Labs Canonical
    설치 방식 단일 바이너리, 스크립트 Snap 패키지
    데이터베이스 SQLite (기본), PostgreSQL, MySQL 등 etcd
    장점 극강의 경량성, 빠른 설치, 단일 파일 모듈식 애드온, 스냅 자동 업데이트, 고가용성 용이
    적합 환경 초소형 엣지, IoT, CI/CD 개발/테스트, 데스크톱, 엣지

    경량 쿠버네티스 설치, 어디서부터 시작할까? (실전 구현)

    이제 직접 설치해보는 과정을 보여드릴게요. 저는 주로 라즈베리 파이나 집에 굴러다니는 미니 PC에 설치해서 쓰고 있거든요. 여기서는 범용적으로 사용할 수 있는 K3s 설치 예시를 들어볼 텐데, MicroK8s도 과정이 비슷하게 간단합니다.

    K3s 설치 예시

    제가 실제로 경험해본 K3s는 정말 😎 쉽습니다. 단 한 줄의 명령어로 서버(Master)와 에이전트(Agent)를 세팅할 수 있거든요.

    1. 서버 노드(Master) 설치

    먼저 클러스터의 컨트롤 플레인(Control Plane) 역할을 할 서버 노드를 깔아봅시다. 보통 가장 먼저 설치하고, 이 노드가 나머지 에이전트 노드들을 관리하게 되거든요. 다음 명령어를 실행하면 K3s가 알아서 설치되고 시작돼요.

    curl -sfL https://get.k3s.io | sh -

    설치가 끝나면 kubectl 명령어를 바로 사용할 수 있게 돼요. 잘 설치됐는지 확인해볼까요?

    sudo k3s kubectl get nodes

    자신의 서버 노드가 Ready 상태로 보일 텐데, 이때 느끼는 쾌감은 정말 🎉 입니다.

    2. 에이전트 노드(Agent) 추가

    이제 클러스터에 워커 노드를 추가할 차례예요. 다른 라즈베리 파이나 미니 PC에 접속해서 다음 명령어를 실행하면 되는데, 여기서 중요한 게 K3S_URL과 K3S_TOKEN입니다.

    • K3S_URL: 서버 노드의 IP 주소를 지정합니다.
    • K3S_TOKEN: 서버 노드에서 생성된 토큰이에요. 이 토큰은 /var/lib/rancher/k3s/server/node-token 파일에서 확인할 수 있습니다.
    # 서버 노드에서 토큰 확인
sudo cat /var/lib/rancher/k3s/server/node-token

# 에이전트 노드에서 설치 (TOKEN과 SERVER_IP는 자신의 환경에 맞게 변경)
curl -sfL https://get.k3s.io | K3S_URL="https://YOUR_SERVER_IP:6443" K3S_TOKEN="K10xxxxxxxxxxxxxxxxxxxx" sh -

    모든 에이전트 노드에 이 과정을 반복하면 되는데, 몇 분이 지난 후 서버 노드에서 다시 sudo k3s kubectl get nodes를 실행해보면 새로 추가된 노드들이 보일 거예요. 정말 신기하지 않나요? 😁

    K3s 클러스터에 연결된 노드들의 상태를 보여주는 터미널 화면

    이미지: K3s 클러스터에 연결된 노드들의 상태를 보여주는 터미널 화면입니다.

    홈랩에서 겪은 삽질 경험과 해결책 (주의사항/트러블슈팅)

    13년차 엔지니어라고 해서 삽질을 안 하는 건 아닙니다. 오히려 더 많이 해요. 😅 특히 엣지 환경에서는 예상치 못한 변수들이 많아서 몇 번은 머리를 쥐어뜯었거든요. 제가 직접 겪었던 몇 가지 문제와 그 해결책을 공유해볼게요.

    ⚠️ 1. 네트워크 문제: 노드 간 통신 장애

    정말 흔한 문제예요. 처음엔 분명 잘 연결된 것 같았는데, 어느 순간 노드(Node)들이 NotReady 상태로 바뀌는 경우가 있더라고요. 대부분 방화벽(Firewall)이나 네트워크 설정 때문이었습니다. 특히 라즈베리 파이 같은 작은 디바이스들은 무선 LAN(랜)을 많이 쓰는데, 공유기 설정 때문에 서로 통신이 안 되는 경우도 있었어요.

    • 해결책:
    • 방화벽 확인: ufw나 firewalld 같은 방화벽이 6443 포트(Port)나 다른 쿠버네티스 관련 포트를 막고 있지 않은지 확인하고 열어줍니다.
    • IP 주소 고정: DHCP(동적 호스트 구성 프로토콜)로 IP가 자꾸 바뀌면 노드 통신이 끊기기도 해요. 각 노드의 IP 주소를 고정(Static IP)으로 설정하는 게 좋습니다.
    • Cilium/Flannel 로그 확인: CNI(Container Network Interface) 플러그인(Plug-in)인 Cilium이나 Flannel 로그를 확인하면 네트워크 문제를 진단하는 데 정말 큰 도움이 돼요.

    ⚠️ 2. 리소스 제한: 메모리/CPU 부족

    라즈베리 파이 3B+나 4B 모델에 1GB, 2GB 램(RAM)을 가진 노드들을 운영하다 보면 파드(Pod) 몇 개만 돌려도 메모리가 부족하다고 아우성칠 때가 많아요. 특히 메트릭 서버(Metrics Server)나 모니터링 툴(Monitoring Tool)까지 올리면 순식간에 리소스가 바닥나더라고요.

    • 해결책:
    • 오버프로비저닝 금지: 😭 욕심부리지 마세요! 필요한 파드만 최소한으로 배포합니다.
    • 리소스 요청/제한 설정: 디플로이먼트(Deployment) YAML 파일에 resources.requests와 resources.limits를 명확하게 설정해서 파드가 필요한 만큼만 쓰도록 제한하는 거예요.
    • 스왑(Swap) 공간 활용: 성능 저하를 감수하고라도 메모리가 정말 부족하다면 스왑 공간을 활성화하는 것도 한 방법입니다. 하지만 이건 최후의 수단으로 생각하세요.

    ⚠️ 3. SD 카드 수명 문제

    라즈베리 파이에서 SD 카드를 부팅 디스크로 쓸 때, 쿠버네티스는 로그(Log)나 데이터베이스 쓰기 작업이 정말 많아서 SD 카드 수명이 급격히 줄어들 수 있어요. 실제로 저도 몇 번 SD 카드가 사망하는 경험을 했습니다. 💀

    • 해결책:
    • USB SSD 사용: 가능하면 USB 외장 SSD(솔리드 스테이트 드라이브)를 부팅 디스크로 쓰는 게 정말 좋아요. 훨씬 빠르고 안정적이며 수명도 길거든요.
    • 로그 회전(Log Rotation) 설정: 로그 파일이 너무 커지지 않도록 logrotate를 설정해서 관리하는 게 중요합니다.

    성능 모니터링 및 리소스 관리 팁 (추가적인 팁)

    경량 쿠버네티스라고 해서 모니터링을 소홀히 하면 안 돼요. 오히려 작은 시스템일수록 더욱 꼼꼼하게 지켜봐야 합니다. 제가 실제로 쓰는 몇 가지 팁을 알려드릴게요.

    1. Prometheus/Grafana로 시각화

    작은 규모의 클러스터라도 프로메테우스(Prometheus)와 그라파나(Grafana)는 거의 필수라고 생각해요. 노드의 CPU(중앙 처리 장치), 메모리(Memory) 사용량, 네트워크 트래픽(Traffic) 등을 실시간으로 시각화해서 볼 수 있거든요. K3s나 MicroK8s 모두 Prometheus를 쉽게 설치할 수 있는 방법을 제공합니다.

    # MicroK8s의 경우
microk8s enable prometheus

# K3s의 경우, Helm 차트(Chart)로 설치
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
helm install prometheus prometheus-community/kube-prometheus-stack

    저는 Grafana 대시보드를 띄워놓고 커피 마시면서 클러스터 상태를 확인하는 게 소소한 낙이에요. 😄

    2. 리소스 쿼터(Resource Quotas) 설정

    여러 애플리케이션(Application)을 배포할 때, 특정 네임스페이스(Namespace)나 파드가 너무 많은 리소스를 독점하지 않도록 리소스 쿼터를 설정하는 게 중요해요. 특히 홈랩처럼 리소스가 제한적인 환경에서는 더욱 그렇거든요.

    # resource-quota.yaml
apiVersion: v1
kind: ResourceQuota
metadata:
  name: pod-quota
spec:
  hard:
    pods: "10"
    requests.cpu: "1"
    requests.memory: "1Gi"
    limits.cpu: "2"
    limits.memory: "2Gi"

    kubectl apply -f resource-quota.yaml -n my-namespace

    이렇게 하면 my-namespace 안에서는 최대 10개의 파드만 생성할 수 있고, CPU와 메모리도 지정된 범위 내에서만 쓸 수 있게 된답니다. 💸

    Grafana 대시보드에서 경량 쿠버네티스 클러스터의 실시간 리소스 사용량을 모니터링하는 모습

    이미지: Grafana 대시보드에서 경량 쿠버네티스 클러스터의 실시간 리소스 사용량을 모니터링하는 모습입니다.

    실제 운영 사례와 얻은 교훈 (검증/결과)

    저는 홈랩에서 K3s 클러스터를 여러 대 운영하고 있어요. 주로 하는 일들을 정리해보면 다음과 같습니다.

    • 개인 웹사이트/블로그 호스팅: Nginx Ingress Controller(엔진엑스 인그레스 컨트롤러)와 Cert-Manager(서트 매니저)를 활용해서 Let’s Encrypt(렛츠 인크립트) SSL(보안 소켓 계층) 인증서를 자동으로 발급받아 제 블로그를 안전하게 운영하고 있어요.
    • IoT 데이터 수집 및 처리: 여러 센서(Sensor)에서 들어오는 데이터를 Kafka(카프카)로 수집하고, Go(고) 언어로 작성된 경량 워커(Worker) 파드에서 데이터를 처리한 후 InfluxDB(인플럭스디비)에 저장하는 파이프라인(Pipeline)을 구축했어요.
    • CI/CD 테스트 환경: 작은 규모의 개발 프로젝트를 할 때, 젠킨스(Jenkins)나 아르고 CD(Argo CD)를 K3s 클러스터에 배포해서 CI/CD(지속적 통합/지속적 배포) 파이프라인 테스트 환경으로 활용하고 있습니다.

    이런 실제 운영 사례들을 통해 얻은 가장 큰 교훈은, ‘작은 것이 아름답다’는 거예요. 😊 복잡하고 무거운 쿠버네티스 기능을 모두 필요로 하지 않는 엣지 환경에서는 K3s나 MicroK8s처럼 핵심 기능에만 집중하고 가볍게 동작하는 솔루션이 훨씬 더 효율적이더라고요.

    물론, 완전한 프로덕션(Production) 환경에서 엔터프라이즈(Enterprise)급 요구사항을 만족시키기에는 제약이 있을 수 있어요. 하지만 소규모 팀, 홈랩, IoT 디바이스, 임베디드(Embedded) 시스템 같은 곳에서는 정말 ‘게임 체인저(Game Changer)’라고 할 수 있죠. 경량 쿠버네티스 덕분에 엣지 컴퓨팅의 문턱이 훨씬 낮아졌다고 저는 생각합니다.

    경량 쿠버네티스의 주요 장점과 고려해야 할 한계점을 시각적으로 요약한 인포그래픽

    이미지: 경량 쿠버네티스의 주요 장점과 고려해야 할 한계점을 시각적으로 요약한 인포그래픽입니다.

    마무리: 엣지 쿠버네티스의 미래와 다음 단계

    오늘은 K3s와 MicroK8s를 중심으로 경량 엣지 쿠버네티스를 구축하고 운영했던 제 경험을 공유해드렸어요. 처음엔 단순히 ‘작은 쿠버네티스’ 정도로 생각했는데, 직접 써보니까 엣지 환경에 특화된 기능과 철학이 담겨 있더라고요. 설치는 쉽고 리소스 소모는 적어서, 저처럼 홈랩을 꾸리거나 소규모 엣지 프로젝트를 진행하는 분들께는 정말 강력 추천하고 싶은 솔루션입니다. 💪

    물론, 모든 기술이 그렇듯 장점만 있는 건 아니에요. 풀 스택 쿠버네티스가 제공하는 모든 기능을 기대하기보다는, 자신의 환경과 필요한 기능에 맞춰 현명하게 선택하고 활용하는 지혜가 필요합니다. 하지만 ‘경량’이라는 이름표를 달고 엣지 컴퓨팅의 중요한 축으로 자리 잡은 K3s와 MicroK8s의 미래는 앞으로도 계속 밝을 거라고 확신해요.

    다음번에는 이 경량 쿠버네티스 클러스터 위에 GitOps(깃옵스) 환경을 구축해서 애플리케이션 배포를 자동화하는 방법에 대해 다뤄볼까 합니다. 기대해주세요! 혹시 K3s나 MicroK8s를 사용하면서 겪었던 재미있는 경험이나 삽질 스토리가 있다면 댓글로 공유해주세요. 저도 배우는 게 많을 것 같습니다. 😊

  • [k8s] K3s와 AWX 통합 사례 연구: 경량 Kubernetes 자동화 워크플로우 구축

    [k8s] K3s와 AWX 통합 사례 연구: 경량 Kubernetes 자동화 워크플로우 구축

    목차

    안녕하세요, 13년차의 서버실입니다. 오늘은 제가 홈랩에서 직접 경험하고 삽질하면서 얻은 지식 하나를 여러분과 공유해볼게요. 바로 K3s(케이쓰리쓰)와 AWX(에이더블유엑스)를 통합하여 경량 Kubernetes(쿠버네티스) 환경에서 자동화 워크플로우를 구축하는 사례입니다.

    작은 규모의 인프라나 홈랩에서 Kubernetes를 운영하다 보면, 리소스 제약 때문에 고민이 많아지죠. 게다가 반복적인 배포나 설정 변경 작업을 수동으로 하다 보면 시간 낭비는 물론이고 휴먼 에러 발생 확률도 높아지고요. 저도 “이걸 어떻게 하면 좀 더 효율적으로 관리할 수 있을까?” 하는 고민에 빠져있었거든요. 그러다가 경량 Kubernetes인 K3s와 Ansible(앤서블) 기반의 자동화 플랫폼인 AWX의 조합을 떠올리게 됐습니다.

    이 둘을 잘 엮으면 리소스 효율적인 환경에서 강력한 자동화 시스템을 만들 수 있겠다는 확신이 들었죠. 그래서 직접 부딪혀가며 구축해봤고, 그 과정과 삽질 경험을 솔직하게 풀어보려 합니다. 혹시 여러분도 비슷한 고민을 하고 계셨다면, 이 글이 좋은 가이드가 될 수 있을 거예요. 💡

    K3s와 AWX를 통합한 자동화 워크플로우의 전체 아키텍처 다이어그램

    K3s 클러스터 위에 AWX가 배포되어 외부 Git 리포지토리의 Ansible 플레이북을 가져와 다른 K3s/Kubernetes 클러스터에 배포하는 통합 아키텍처 다이어그램입니다.

    K3s와 AWX, 왜 이 조합일까요?

    먼저, 이 두 가지 기술이 무엇인지, 그리고 왜 함께 사용하면 시너지가 나는지 간단하게 짚고 넘어가겠습니다.

    K3s: 가볍지만 강력한 경량 Kubernetes

    K3s(케이쓰리쓰)는 Rancher Labs(랜처 랩스)에서 만든 경량 Kubernetes(쿠버네티스) 배포판입니다. 이름에서 알 수 있듯이 ‘K8s(케이츠) – 5 = K3s’라는 유머러스한 의미를 가지고 있어요. 그만큼 바이너리 크기가 작고, 메모리 사용량도 적으니까요. 일반적인 Kubernetes는 컨트롤 플레인(Control Plane) 구성 요소들이 많은 리소스를 요구하는데, K3s는 SQLite를 기본 데이터베이스로 사용하고 불필요한 기능을 제거해서 엣지 컴퓨팅(Edge Computing), IoT(사물 인터넷), 또는 저사양 환경에 정말 딱 맞습니다. 제가 홈랩에서 운영하는 라즈베리 파이(Raspberry Pi) 클러스터 같은 곳에 정말 찰떡이더라고요. ✅

    AWX: Ansible 자동화 플랫폼의 중앙 허브

    AWX(에이더블유엑스)는 Red Hat(레드햇)의 Ansible Tower(앤서블 타워)의 오픈소스 업스트림 프로젝트입니다. Ansible(앤서블)은 강력한 IT 자동화 도구인데, AWX는 이 Ansible 플레이북(Playbook)들을 웹 UI를 통해 중앙에서 관리하고 실행할 수 있게 해줍니다. 그냥 복잡한 커맨드 라인(Command Line) 없이도 프로젝트, 인벤토리(Inventory), 자격 증명(Credential) 등을 관리하고, 잡 템플릿(Job Template)을 만들어 반복적인 작업을 예약하거나 실행 결과를 쉽게 확인할 수 있죠. 특히 팀 단위로 자동화 작업을 공유하고 접근 제어를 해야 할 때 진짜 빛을 발합니다. 🎉

    통합의 시너지: 경량 K3s 위의 자동화 플랫폼

    저는 K3s의 가벼움 위에 AWX를 올려서 경량 Kubernetes 환경을 위한 자동화 허브를 구축하고 싶었습니다. K3s에서 돌아가는 애플리케이션의 배포나 설정을 AWX를 통해 관리하려는 거였거든요. 예를 들어, 새로운 컨테이너 이미지를 빌드하면 AWX가 자동으로 K3s 클러스터에 배포하도록 하거나, 특정 서비스의 스케일링(Scaling) 작업을 AWX 잡 템플릿으로 만들어서 필요할 때마다 클릭 한 번으로 실행하는 식입니다. 이렇게 하면 인프라 관리가 정말 수월해지더라고요. 💡

    실전 구현: K3s 위에 AWX 배포하기

    이제 제가 직접 K3s 클러스터에 AWX를 배포했던 과정을 단계별로 설명해 드릴게요. 저는 이미 K3s 클러스터가 구성되어 있다는 가정하에 진행했습니다. 아직 K3s 설치가 안 되어 있다면, 다음 명령어로 간단하게 설치할 수 있습니다.

    curl -sfL https://get.k3s.io | sh -

    1. AWX Operator 설치

    AWX는 Kubernetes 환경에 AWX Operator(오퍼레이터)를 통해 배포하는 것이 가장 일반적입니다. Operator는 특정 애플리케이션(여기서는 AWX)을 Kubernetes의 컨트롤러처럼 관리해주는 도구라고 생각하시면 돼요. 배포부터 업데이트, 스케일링까지 알아서 처리해주니까요.

    AWX Operator를 설치하려면 공식 AWX Operator 저장소에서 최신 설치 가이드를 확인하시고, 다음 명령어로 설치합니다.

    kubectl apply -f https://raw.githubusercontent.com/ansible/awx-operator/devel/deploy/operator.yaml

    이 명령어가 AWX Operator와 필요한 CRD(Custom Resource Definition, 사용자 정의 리소스 정의)를 모두 설치해줍니다. CRD는 Kubernetes가 AWX라는 새로운 리소스 타입을 이해할 수 있도록 해주는 설정 파일이거든요. 이 과정을 거치면 awx-operator 파드(Pod)가 실행되면서 AWX 인스턴스를 배포할 준비가 완료됩니다.

    2. AWX 인스턴스 배포

    Operator가 준비되었다면, 이제 우리가 원하는 AWX 인스턴스를 생성할 차례입니다. AWX라는 Custom Resource(CR) 객체를 생성하면, Operator가 이 CR을 감지하고 실제 AWX 애플리케이션을 배포해줍니다. 저는 awx.yaml이라는 파일을 만들어서 다음과 같이 설정했습니다.

    apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: my-awx
spec:
  # AWX Operator가 배포할 AWX 인스턴스의 이름
  # 여기서는 my-awx로 지정했습니다.

  # ingressType: Ingress를 사용하여 Kubernetes Ingress를 통해 AWX에 접근하도록 설정합니다.
  # K3s는 기본적으로 Traefik Ingress Controller를 포함하고 있어 편리합니다.
  ingressType: Ingress
  # ingress_host: AWX에 접근할 호스트 이름을 지정합니다.
  # 실제 환경에서는 DNS에 이 호스트를 등록해야 합니다.
  ingress_host: awx.myhomelab.local
  
  # 기타 설정 (필요에 따라 주석 해제 및 수정)
  # postgres_storage_class: AWX 데이터베이스를 위한 Persistent Volume Claim(PVC)의 StorageClass를 지정합니다.
  # 홈랩 환경에서는 hostPath나 local-storage 등을 사용할 수 있습니다.
  # postgres_storage_class: standard
  
  # web_extra_volume_mounts: AWX 웹 파드에 추가 볼륨을 마운트할 때 사용합니다.
  # e.g., 인증서 마운트 등
  # tasks_extra_volume_mounts: AWX 태스크 파드에 추가 볼륨을 마운트할 때 사용합니다.
  
  # image_version: 사용할 AWX 이미지 버전 (특정 버전을 고정할 경우)
  # image_version: "23.3.0"
  
  # resource_requirements: AWX 파드들의 리소스 요청/제한을 설정합니다.
  # 작은 환경에서는 이 부분을 적절히 조절해야 합니다.
  # web_resource_requirements:
  #   requests:
  #     cpu: 500m
  #     memory: 1Gi
  #   limits:
  #     cpu: 1000m
  #     memory: 2Gi

    이 파일을 저장하고 kubectl apply -f awx.yaml 명령어를 실행하면 AWX Operator가 AWX 인스턴스에 필요한 Deployment(디플로이먼트), Service(서비스), Ingress(인그레스), Persistent Volume Claim(PVC) 등을 자동으로 생성하기 시작합니다.

    K3s 클러스터에 AWX 파드들이 정상적으로 실행 중임을 나타내는 터미널 화면

    AWX 웹 UI의 로그인 화면 또는 kubectl get pods -n awx 명령어를 실행했을 때 AWX 관련 파드들이 모두 Running 상태인 것을 보여주는 스크린샷입니다.

    ⚠️ 삽질 경험과 트러블슈팅

    제가 이 과정을 진행하면서 겪었던 몇 가지 삽질 경험과 해결 방법을 공유합니다. 여러분은 저처럼 헤매지 않으시길 바라요! 😂

    1. 리소스 부족 문제

    K3s는 가볍지만, AWX는 생각보다 많은 리소스를 필요로 합니다. 특히 데이터베이스(PostgreSQL)와 웹, 태스크 파드들이 동시에 돌아가기 때문에, 2GB RAM 이하의 시스템에서는 버벅이거나 파드가 계속 재시작되는 문제가 발생할 수 있어요. 최소 4GB RAM, 2코어 CPU 이상을 권장합니다. 저도 처음엔 라즈베리 파이 4(4GB 모델)에서 돌렸는데, 다른 서비스들과 함께 돌리니 정말 아슬아슬하더라고요. 결국 8GB 모델로 업그레이드하거나, AWX 전용 노드를 따로 두는 것을 고려하게 됐습니다.

    해결책: awx.yaml 파일의 resource_requirements 섹션을 통해 각 파드의 리소스 요청(requests)과 제한(limits)을 조절할 수 있습니다. 하지만 너무 낮추면 성능 문제가 발생하니, 하드웨어 사양을 충분히 확보하는 것이 최고의 방법입니다.

    2. Persistent Volume(영구 볼륨) 설정

    AWX는 데이터베이스(PostgreSQL)와 작업 실행 로그 등을 저장하기 위해 Persistent Volume(PV, 영구 볼륨)이 필요합니다. K3s는 기본적으로 local-path-provisioner(로컬 패스 프로비저너)를 내장하고 있어서 별도의 StorageClass(스토리지 클래스) 설정 없이도 PVC(Persistent Volume Claim)를 생성하면 자동으로 PV가 프로비저닝(Provisioning)됩니다. 하지만 이 방식은 특정 노드에 데이터가 종속되기 때문에 노드 장애 시 데이터 손실 위험이 있습니다.

    해결책: 홈랩 환경에서는 간단하게 hostPath 타입을 사용하여 특정 경로에 데이터를 저장할 수 있지만, 좀 더 안정적인 환경을 원한다면 NFS(네트워크 파일 시스템) 서버를 구축하고 NFS CSI Driver(드라이버)를 설치하여 공유 스토리지를 사용하는 것이 좋습니다. 저도 NFS를 사용해서 여러 노드에서 AWX 파드들이 유연하게 움직일 수 있도록 구성했거든요.

    3. Ingress(인그레스) 접근 문제

    ingress_host를 설정했지만, 웹 브라우저에서 접속이 안 되는 경우가 있었습니다. K3s는 기본적으로 Traefik(트래픽) Ingress Controller(인그레스 컨트롤러)를 내장하고 있어 편리합니다. 하지만 제 경우에는 다음과 같은 문제가 있었습니다.

    • DNS 설정: awx.myhomelab.local과 같은 호스트 이름을 사용하려면, 홈랩 내 DNS 서버에 해당 호스트를 등록하거나, 접속하려는 PC의 /etc/hosts (Linux/macOS) 또는 C:\Windows\System32\drivers\etc\hosts (Windows) 파일에 IP 주소와 호스트 이름을 직접 매핑해주어야 합니다. 
      # /etc/hosts 예시
192.168.1.100 awx.myhomelab.local # K3s 마스터 노드의 IP 주소
    • Traefik 설정: 가끔 Traefik이 외부 트래픽을 제대로 라우팅(Routing)하지 못하는 경우가 있는데, K3s 설치 시 Traefik 관련 옵션을 확인하거나, Traefik 대시보드(보통 http://<k3s_master_ip>:8080/dashboard/)에서 Ingress Route(인그레스 라우트)가 제대로 생성되었는지 확인해야 합니다.

    해결책: 저는 /etc/hosts 파일을 수정하고, kubectl get ingress -n awx 명령어로 AWX Ingress 리소스가 정상적으로 생성되었는지 확인하면서 문제를 해결했습니다.

    검증 및 결과: AWX로 K3s 자동화하기

    여러 삽질 끝에 드디어 AWX가 K3s 클러스터 위에 성공적으로 배포되었습니다! 🎉 이제 웹 브라우저를 열고 설정했던 ingress_host로 접속하면 AWX 로그인 화면이 보일 겁니다. 초기 관리자 비밀번호는 AWX Operator가 Secret(시크릿)으로 생성해두는데, 다음 명령어로 확인할 수 있습니다.

    kubectl get secret my-awx-admin-password -o jsonpath='{.data.password}' | base64 --decode

    로그인 후, 저는 간단한 Ansible 플레이북을 만들어서 K3s 클러스터의 노드 목록을 조회하는 작업을 자동화해봤습니다. AWX에서 Project(프로젝트), Inventory(인벤토리), Credential(자격 증명)을 설정하고 Job Template(잡 템플릿)을 생성한 뒤 실행하니, 깔끔하게 K3s 노드 정보가 출력되는 것을 확인할 수 있었습니다. 이 화면을 보는 순간, 그동안의 고생이 눈 녹듯 사라지더라고요! 정말 뿌듯했어요. 😄

    AWX 웹 UI에서 K3s 노드 목록을 조회하는 Ansible 잡이 성공적으로 실행된 결과 화면

    AWX 웹 UI에서 Ansible 플레이북이 성공적으로 실행되어 K3s 클러스터의 노드 목록을 출력하는 잡 실행 결과 화면 스크린샷입니다. 초록색 성공 메시지와 함께 결과가 표시됩니다.

    마무리: 경량 Kubernetes 자동화, 여러분도 해보세요!

    K3s와 AWX를 통합하여 경량 Kubernetes 환경에서 자동화 워크플로우를 구축한 경험은 저에게 정말 값진 시간이었습니다. 비록 중간중간 삽질도 많이 했지만, 그 과정에서 얻은 지식과 해결 능력은 어떤 책에서도 배울 수 없는 것이었거든요.

    주요 배운 점:

    • K3s는 가볍지만, AWX처럼 리소스를 많이 쓰는 애플리케이션을 올릴 때는 충분한 하드웨어 리소스 계획이 필요하다는 것.
    • Persistent Volume 설정은 안정적인 운영을 위한 핵심이라는 것. (홈랩이라도 NFS는 정말 중요합니다.)
    • Kubernetes Ingress와 DNS 설정은 항상 꼼꼼하게 확인해야 한다는 것.
    • AWX Operator를 사용하면 복잡한 AWX 배포를 Kubernetes 스타일로 정말 간단하게 할 수 있다는 것.

    이 조합은 특히 저처럼 홈랩을 운영하거나, 소규모 팀에서 효율적인 인프라 자동화를 목표로 할 때 정말 강력한 솔루션이 될 수 있다고 확신합니다. 여러분도 직접 K3s와 AWX를 설치하고 이것저것 만져보면서 자신만의 자동화 워크플로우를 구축해보시길 강력히 추천합니다. 직접 해보면서 얻는 경험만큼 값진 건 없으니까요! 💪

    다음 글에서는 AWX를 이용한 좀 더 복잡한 GitOps(깃옵스) 파이프라인 구축에 대해 더 깊이 다뤄볼 예정입니다. 기대해주세요! 😄

    K3s와 AWX 통합으로 얻을 수 있는 주요 장점을 시각적으로 요약한 인포그래픽

    K3s와 AWX 통합의 주요 장점 (예: 리소스 효율성, 중앙 집중식 자동화, 빠른 배포, 간편한 관리)을 시각적으로 요약한 인포그래픽입니다.

  • [k8s] k3s와 MicroK8s 비교: 경량 쿠버네티스 환경 선택 가이드

    목차

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

    홈랩을 운영하다 보면 꼭 한 번씩 마주치는 고민이 있어요. “쿠버네티스(Kubernetes)는 써보고 싶은데, 풀스택 k8s를 올리기엔 서버가 너무 작다…” 저도 딱 그랬거든요. 라즈베리파이(Raspberry Pi) 클러스터 위에 뭔가 올려보려고 했는데, 일반 쿠버네티스는 메모리만 수 GB를 잡아먹으니 엄두가 안 나더라고요.

    그래서 찾게 된 게 경량 쿠버네티스(Lightweight Kubernetes)입니다. 그중에서도 현재 가장 많이 언급되는 두 가지가 바로 k3s와 MicroK8s예요. 이 둘, 뭐가 다른지 처음엔 저도 진짜 헷갈렸습니다. 이름도 비슷하고 목적도 비슷한 것 같고… 근데 실제로 써보면 꽤 다르거든요.

    이번 글에서는 제가 직접 두 솔루션을 홈랩에서 돌려보면서 느낀 점, 그리고 어떤 상황에서 어떤 걸 선택해야 하는지 정리해 드릴게요. 엣지 컴퓨팅(Edge Computing) 환경이나 라즈베리파이 쿠버네티스 구성을 고민 중이신 분들께 특히 도움이 될 거예요.

    k3s와 MicroK8s의 전체 아키텍처 구조를 한눈에 비교한 다이어그램. 각각의 구성 요소와 설계 철학의 차이를 보여줍니다.

    k3s와 MicroK8s, 각각 어떤 녀석인가요?

    k3s — “진짜 가볍게 만들어 버렸다”

    k3s는 Rancher Labs(현재 SUSE)에서 만든 경량 쿠버네티스 배포판입니다. 공식 CNCF(Cloud Native Computing Foundation) 인증 프로젝트이기도 해요. 핵심 철학은 딱 하나예요. “싱글 바이너리(single binary)로 모든 걸 해결하자.”

    쉽게 말해, etcd(이티시디, 쿠버네티스의 상태 저장소) 대신 기본적으로 SQLite를 쓰고, 불필요한 컴포넌트를 싹 쳐냈어요. 덕분에 바이너리 하나가 약 100MB 남짓이고, 메모리도 정말 적게 씁니다. 라즈베리파이 같은 저사양 ARM 기기에서도 잘 돌아가는 이유가 여기 있어요.

    • 단일 바이너리로 설치 및 실행
    • 기본 데이터스토어: SQLite (고가용성 구성 시 etcd 또는 외부 DB 사용 가능)
    • ARM 아키텍처 공식 지원 (라즈베리파이 최적)
    • Flannel(플란넬) CNI 기본 내장
    • Traefik(트래픽) Ingress Controller 기본 포함
    • CNCF 공식 인증 쿠버네티스

    MicroK8s — “Ubuntu 생태계에서 편하게”

    MicroK8s는 Canonical(캐노니컬, Ubuntu 만드는 회사)에서 만든 경량 쿠버네티스예요. 설치 방식이 좀 독특한데, Snap(스냅) 패키지 매니저를 통해 설치합니다. Ubuntu 환경이라면 진짜 설치가 간단해요.

    k3s와 달리 MicroK8s는 애드온(addon) 시스템이 핵심이에요. 기본 설치는 가볍게 하고, 필요한 기능(DNS, 대시보드, Ingress, 스토리지 등)을 명령어 하나로 활성화하는 방식이거든요. 개발 환경이나 Ubuntu 서버에서 빠르게 쿠버네티스를 시험해보고 싶을 때 특히 편합니다.

    • Snap 패키지로 설치 (Ubuntu/Linux 최적화)
    • 애드온 시스템으로 필요한 기능만 활성화
    • 단일 노드 개발 환경에 강점
    • Canonical의 지원 및 업스트림 쿠버네티스와 빠른 동기화
    • ARM 지원 (단, k3s 대비 리소스 사용량이 다소 높음)

    k3s vs MicroK8s 핵심 스펙 비교

    말로만 하면 헷갈리니까 표로 정리해 봤어요. 제가 직접 테스트하면서 확인한 내용 위주입니다.

    항목 k3s MicroK8s
    개발사 Rancher Labs / SUSE Canonical (Ubuntu)
    설치 방식 curl 스크립트 / 단일 바이너리 Snap 패키지
    기본 데이터스토어 SQLite (소규모) / etcd 선택 가능 dqlite (분산 SQLite)
    기본 CNI Flannel Calico (기본 활성화)
    Ingress 기본 포함 Traefik (기본 활성화) nginx (애드온으로 활성화)
    ARM 지원 매우 우수 (라즈베리파이 최적) 지원 (단, x86 최적화)
    멀티노드 클러스터 매우 간단 가능 (설정 다소 복잡)
    CNCF 인증 ✅ 인증 ✅ 인증
    주요 사용 환경 엣지, IoT, 라즈베리파이, 프로덕션 경량화 개발/테스트, Ubuntu 서버, 단일 노드
    OS 의존성 낮음 (대부분의 Linux 지원) 높음 (Snap 지원 OS 필요)

    💡 핵심 포인트: 둘 다 CNCF 공식 인증을 받은 쿠버네티스예요. 즉, 표준 kubectl 명령어와 YAML 매니페스트가 그대로 동작합니다. “이거 진짜 쿠버네티스 맞아?” 걱정 안 하셔도 돼요.

    k3s 설치: 진짜 이렇게 간단해도 되나?

    처음 k3s를 설치했을 때 솔직히 당황했어요. 너무 간단해서요. “이게 다야?” 싶었거든요. 라즈베리파이 OS나 Ubuntu 기준으로 설명드릴게요.

    마스터 노드(서버) 설치

    # k3s 서버(마스터 노드) 설치 — 딱 한 줄입니다
curl -sfL https://get.k3s.io | sh -

# 설치 완료 후 상태 확인
sudo systemctl status k3s

# 노드 상태 확인
sudo kubectl get nodes

    이게 전부예요. 진짜로요. 스크립트가 k3s 바이너리를 받아서 systemd 서비스로 등록까지 해줍니다. 설치 후 1~2분 기다리면 노드가 Ready 상태가 돼요.

    워커 노드(에이전트) 추가

    # 마스터 노드에서 토큰 확인
sudo cat /var/lib/rancher/k3s/server/node-token

# 워커 노드에서 실행 (K3S_TOKEN과 서버 IP를 바꿔주세요)
curl -sfL https://get.k3s.io | K3S_URL=https://마스터노드IP:6443 \
  K3S_TOKEN=여기에토큰값 sh -

    라즈베리파이 3대로 클러스터 구성할 때 이 명령어로 10분 만에 끝냈어요. 삽질 없이요. 😄

    kubeconfig 설정 (로컬 PC에서 접속)

    # 마스터 노드에서 kubeconfig 복사
sudo cat /etc/rancher/k3s/k3s.yaml

# 로컬 PC의 ~/.kube/config 에 붙여넣기
# server: https://127.0.0.1:6443 부분을 실제 서버 IP로 변경
# 예: server: https://192.168.1.100:6443

    ⚠️ 주의: k3s.yaml 파일의 server 주소가 기본적으로 127.0.0.1로 돼 있어요. 원격 접속할 때 반드시 실제 IP로 바꿔줘야 합니다. 이거 놓치면 “connection refused” 보면서 한참 헤맬 수 있어요. 저도 한 30분 고생했었습니다 ㅎㅎ

    MicroK8s 설치: Ubuntu라면 이게 편할 수도

    MicroK8s는 Ubuntu 환경이라면 진짜 편해요. Snap으로 설치하니까요. 다만 Snap이 없는 OS에서는 좀 번거로울 수 있습니다.

    설치 및 기본 설정

    # MicroK8s 설치 (Ubuntu 기준)
sudo snap install microk8s --classic

# 현재 사용자를 microk8s 그룹에 추가 (sudo 없이 사용하려면 필수)
sudo usermod -aG microk8s $USER
newgrp microk8s

# 상태 확인
microk8s status --wait-ready

# kubectl 사용 (microk8s.kubectl 또는 alias 설정)
microk8s kubectl get nodes

# 편하게 쓰려면 alias 등록
alias kubectl='microk8s kubectl'

    애드온 활성화 — 이게 MicroK8s의 핵심이에요

    # DNS 활성화 (거의 필수)
microk8s enable dns

# 대시보드 활성화
microk8s enable dashboard

# Ingress 컨트롤러 활성화
microk8s enable ingress

# 스토리지(hostpath) 활성화
microk8s enable hostpath-storage

# 여러 개 한 번에 활성화
microk8s enable dns dashboard ingress hostpath-storage

# 활성화된 애드온 확인
microk8s status

    MicroK8s의 애드온 시스템과 k3s 멀티노드 클러스터 구성 화면. 각각의 설치 및 설정 방식의 차이를 보여줍니다.

    MicroK8s 멀티노드 클러스터 구성

    # 마스터 노드에서 조인 토큰 생성
microk8s add-node

# 출력된 명령어를 워커 노드에서 실행 (예시)
# microk8s join 192.168.1.100:25000/토큰값/해시값

    k3s보다 조금 더 손이 가긴 하지만, 출력된 명령어를 그대로 복붙하면 돼서 어렵진 않아요.

    ⚠️ 실제로 써보면서 만난 문제들

    둘 다 써보면서 “아, 이거 주의해야 하는구나” 싶었던 것들 솔직하게 공유할게요.

    k3s에서 자주 만나는 문제들

    • 라즈베리파이 cgroup 설정: 라즈베리파이 OS에서 k3s 실행 시 cgroup(컨트롤 그룹, 리소스 제어 메커니즘) 설정이 안 돼 있으면 노드가 NotReady 상태로 뜹니다. /boot/cmdline.txt (또는 /boot/firmware/cmdline.txt)에 cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1를 추가하고 재부팅해야 해요.
    • Traefik vs 내 Ingress 충돌: k3s는 Traefik을 기본으로 깔아줘요. 근데 nginx Ingress를 따로 쓰고 싶다면 k3s 설치 시 --disable traefik 옵션을 줘야 합니다. 나중에 충돌 나면 진짜 원인 찾기 어렵거든요.
    • 방화벽 포트: 멀티노드 구성 시 6443(API 서버), 8472(Flannel VXLAN), 10250(kubelet) 포트가 열려있어야 해요. UFW 켜놓고 왜 에이전트가 안 붙나 한참 봤던 경험이 있어요.

    MicroK8s에서 자주 만나는 문제들

    • Snap 업데이트 자동 재시작: Snap 패키지 특성상 자동 업데이트가 되면서 MicroK8s가 재시작되는 경우가 있어요. 프로덕션에서 쓴다면 sudo snap refresh --hold microk8s로 자동 업데이트를 잠시 홀드해두는 게 좋습니다.
    • Snap 미지원 OS: CentOS나 일부 최소화 배포판에서는 Snap 자체가 없어서 설치가 번거로워요. 이런 환경에선 k3s가 훨씬 편합니다.
    • DNS 애드온 활성화 순서: 다른 애드온보다 DNS를 먼저 활성화해야 해요. 순서 안 지키면 파드 간 통신이 안 되는 경우가 있더라고요.

    💡 공통 팁: 두 솔루션 모두 kubectl 명령어는 동일하게 사용할 수 있어요. 한쪽에서 작성한 YAML 매니페스트를 다른 쪽에서 그대로 apply해도 됩니다. 그 점은 진짜 편하더라고요.

    간단한 애플리케이션 배포로 검증해보기

    설치만 하고 끝내면 아쉽죠. 간단한 nginx 파드를 배포해서 정상 동작을 확인해 봅시다. 두 솔루션 모두 동일한 YAML로 테스트할 수 있어요.

    # nginx-test.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-test
  labels:
    app: nginx-test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx-test
  template:
    metadata:
      labels:
        app: nginx-test
    spec:
      containers:
      - name: nginx
        image: nginx:stable
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-test-svc
spec:
  selector:
    app: nginx-test
  ports:
  - port: 80
    targetPort: 80
  type: NodePort
    # 배포
kubectl apply -f nginx-test.yaml

# 파드 상태 확인 (Running이 되어야 정상)
kubectl get pods -o wide

# 서비스 확인 (NodePort 번호 확인)
kubectl get svc nginx-test-svc

# 접속 테스트 (NodePort 번호는 위에서 확인한 번호로)
curl http://노드IP:NodePort번호

    “Welcome to nginx!” 가 뜨면 성공입니다! 🎉 이 YAML은 k3s든 MicroK8s든 동일하게 동작해요.

    kubectl get nodes와 get pods 명령어로 확인한 클러스터 정상 동작 결과. 두 노드 모두 Ready 상태이며 파드가 Running 중인 것을 확인할 수 있습니다.

    결국 뭘 골라야 할까? — 상황별 선택 가이드

    “그래서 뭐 써요?”라는 질문을 제일 많이 받아요. 솔직히 말씀드리면, 상황에 따라 달라요. 제가 정리한 선택 기준 공유해 드릴게요.

    k3s를 선택해야 하는 경우

    • ✅ 라즈베리파이나 ARM 기기를 사용하는 경우 — k3s가 압도적으로 유리해요
    • ✅ 엣지 컴퓨팅, IoT 환경 — 리소스가 제한적인 환경에서의 프로덕션 배포
    • ✅ 멀티노드 클러스터를 빠르게 구성해야 할 때
    • ✅ Ubuntu 외 OS(CentOS, Debian, Alpine 등)를 사용하는 경우
    • ✅ CI/CD 파이프라인에 경량 쿠버네티스 환경이 필요할 때
    • ✅ Snap을 쓰기 싫거나 쓸 수 없는 환경

    MicroK8s를 선택해야 하는 경우

    • ✅ Ubuntu 서버/데스크탑이 주 환경인 경우 — 설치와 관리가 정말 편해요
    • ✅ 로컬 개발/테스트 환경 — 단일 노드에서 빠르게 시험해볼 때
    • ✅ 애드온 시스템이 매력적인 경우 — 필요한 기능을 명령어 하나로 켜고 끄고 싶을 때
    • ✅ Canonical 생태계와 통합이 필요한 경우 (Ubuntu Pro, Landscape 등)
    • ✅ 업스트림 쿠버네티스 최신 버전을 빠르게 따라가고 싶을 때

    제 개인적인 결론

    저는 홈랩에서 라즈베리파이 클러스터는 k3s, x86 Ubuntu 서버에서 빠른 테스트는 MicroK8s를 씁니다. 둘 다 훌륭한 도구예요. 어느 쪽을 선택하든 “진짜 쿠버네티스”를 배울 수 있고, 나중에 풀스택 k8s로 넘어가도 배운 게 그대로 써먹힙니다.

    k3s와 MicroK8s 상황별 선택 가이드 요약. 사용 환경, 목적, OS에 따른 최적의 선택을 한눈에 정리한 인포그래픽입니다.

    자주 묻는 질문 (FAQ)

    Q. k3s와 MicroK8s는 실제 쿠버네티스랑 호환되나요?

    네, 둘 다 CNCF 공식 인증을 받은 쿠버네티스입니다. 표준 kubectl 명령어와 YAML 매니페스트가 그대로 동작하고, Helm 차트도 사용할 수 있어요.

    Q. 라즈베리파이 4에서 어느 쪽이 더 잘 돌아가나요?

    k3s가 더 유리합니다. ARM 아키텍처 최적화가 잘 돼 있고, 메모리 사용량도 더 적어요. MicroK8s도 ARM을 지원하지만, 라즈베리파이 환경에서는 k3s가 훨씬 검증이 잘 돼 있습니다.

    Q. 나중에 풀스택 쿠버네티스로 마이그레이션하기 어렵나요?

    애플리케이션 레벨(YAML 매니페스트, Helm 차트)은 그대로 이전할 수 있어요. 다만 스토리지 클래스나 네트워크 플러그인 설정은 환경에 맞게 다시 잡아줘야 합니다. 어렵다기보다는 손이 좀 가는 작업이에요.

    Q. 프로덕션 환경에서 써도 되나요?

    k3s는 실제로 엣지 컴퓨팅, 리테일, 제조업 현장 등 다양한 프로덕션 환경에서 사용되고 있습니다. 고가용성(HA) 구성도 지원해요. MicroK8s도 프로덕션 사용이 가능하지만, 일반적으로 개발/테스트 환경에서 더 많이 쓰이는 경향이 있습니다.

    마무리: 일단 설치해 보세요

    k3s와 MicroK8s 비교, 어떠셨나요? 사실 이 글을 쓰면서 다시 한번 느낀 건데, 이 두 도구 모두 “쿠버네티스 진입 장벽을 낮추자”는 목표 하나는 정말 잘 달성했어요. 예전엔 쿠버네티스 클러스터 하나 올리는 데 반나절씩 걸렸는데, 지금은 30분이면 충분하니까요.

    제 추천은 간단해요. 라즈베리파이나 ARM 기기, 또는 멀티노드 엣지 환경이라면 k3s, Ubuntu 서버에서 빠르게 개발/테스트하고 싶다면 MicroK8s. 고민이 길어지면 일단 k3s로 시작해보세요. 단일 명령어 설치에 문서도 풍부하거든요.

    다음 글에서는 k3s 위에 Helm(헬름, 쿠버네티스 패키지 매니저)과 ArgoCD(아르고시디, GitOps 배포 도구)를 올려서 홈랩 GitOps 파이프라인을 구성하는 내용을 다뤄볼 예정입니다. 경량 쿠버네티스를 설치했으면, 이제 그 위에 뭔가를 올려야죠! 🚀

    혹시 설치하다가 막히는 부분이 있으시면 댓글로 남겨주세요. 제가 겪어본 삽질이라면 같이 풀어드릴 수 있을 것 같아요. 😄

  • [k8s] k3s로 경량 쿠버네티스 클러스터 구축: 홈랩과 엣지 완벽 가이드

    [k8s] k3s로 경량 쿠버네티스 클러스터 구축: 홈랩과 엣지 완벽 가이드

    목차

    k3s로 경량 쿠버네티스 클러스터 구축하기: 13년차 엔지니어의 삽질 완전 정복

    안녕하세요, 13년차의 서버실 주인장입니다. 오늘은 제가 최근 홈랩에서 직접 구축해보고, 엣지 컴퓨팅 환경에서도 정말 유용하겠다 싶었던 기술, k3s(케이쓰리 에스)에 대해 이야기해보려고 해요. 기존 쿠버네티스(Kubernetes)는 아무래도 무겁고 복잡해서 홈랩이나 리소스가 제한적인 엣지 환경에 도입하기가 쉽지 않았거든요. 근데 k3s를 만나고 나서 생각이 확 바뀌었습니다. 가볍고 빠르면서도 쿠버네티스의 강력한 기능을 고스란히 쓸 수 있다는 게 정말 매력적이더라고요!

    저도 처음엔 이게 뭔가 싶었는데, 실제로 써보니까 ‘아, 이거 진짜 물건이다!’ 싶었습니다. 제 경험을 바탕으로 k3s 경량 쿠버네티스를 활용해서 클러스터를 어떻게 구축하는지, 그리고 어떤 삽질을 겪었고 어떻게 해결했는지 솔직하게 공유해볼게요. 특히 엣지 컴퓨팅(Edge Computing)이나 저처럼 홈랩(Home Lab)을 운영하는 분들께 큰 도움이 될 거라 생각합니다.

    💡 k3s, 왜 선택했을까? 경량 쿠버네티스의 진짜 매력

    혹시 이런 경험 있으신가요? 작은 라즈베리 파이(Raspberry Pi)나 오래된 미니 PC에 k3s를 포함한 쿠버네티스를 올려보고 싶었는데, 리소스 문제나 복잡한 설치 과정 때문에 포기했던 경험 말이죠. 저도 그랬거든요. 일반적인 쿠버네티스 배포판은 마스터 노드(Master Node) 하나만 해도 꽤 많은 메모리와 CPU를 요구합니다. 그런데 k3s는 이런 제약을 확 낮춰줍니다. 말 그대로 ‘경량(Lightweight)’ 쿠버네티스죠.

    k3s는 Rancher Labs에서 개발한 CNCF(Cloud Native Computing Foundation) 샌드박스 프로젝트로, 리소스가 제한적인 환경, 예를 들면 IoT 디바이스, 엣지 서버, 그리고 저의 사랑스러운 홈랩 같은 곳에 최적화되어 있습니다. 바이너리 파일 하나로 설치가 끝나고, 필요 없는 기능들을 쳐내서 메모리 사용량도 훨씬 적어요. 제가 직접 해보니, 512MB RAM 이상이면 마스터 노드를 구동할 수 있더라고요! 정말 놀랍지 않습니까? 🎉

    k3s 경량 쿠버네티스 클러스터의 간소화된 아키텍처 다이어그램: 마스터 노드와 여러 워커 노드가 연결되어 엣지 및 홈랩 환경에서 효율적으로 동작하는 모습을 보여줍니다.

    k3s 기본 이해: 경량 쿠버네티스의 핵심 개념

    쉽게 말해 k3s는 쿠버네티스(Kubernetes)의 모든 핵심 기능을 제공하면서도, 배포판을 경량화한 버전입니다. k3s는 기존 쿠버네티스가 제공하는 API Server, Controller Manager, Scheduler, etcd 같은 핵심 컴포넌트들을 모두 포함하고 있어요. 하지만 몇 가지 차이점이 있습니다.

    • 단일 바이너리(Single Binary): 설치 파일이 하나로 되어 있어 배포가 정말 간편합니다.
    • SQLite3 내장(Embedded SQLite3): 기본적으로 외부 etcd 대신 SQLite3를 데이터 저장소로 사용합니다. 물론 PostgreSQL, MySQL, etcd 등 외부 DB도 연결할 수 있어요.
    • 불필요한 기능 제거: 레거시(Legacy) 코드나 클라우드 제공업체(Cloud Provider) 관련 기능을 제거하여 경량화했습니다.
    • 컨테이너 런타임(Container Runtime) 변경: 도커(Docker) 대신 containerd(컨테이너디)를 기본 컨테이너 런타임으로 사용합니다.

    이런 특징들 덕분에 k3s는 일반적인 쿠버네티스에 비해 설치도 빠르고 리소스 소모도 적어서, 소규모 프로젝트나 학습용, 그리고 저처럼 홈랩에서 다양한 실험을 해보고 싶을 때 최적의 선택이 됩니다. 컨테이너 오케스트레이션(Container Orchestration)이라는 쿠버네티스의 핵심 개념은 그대로 가져가면서도, 훨씬 쉽게 접근할 수 있게 해주는 거죠.

    실전! k3s 경량 쿠버네티스 클러스터 구축 스텝별 가이드

    자, 이제 직접 k3s 클러스터를 구축해볼 시간입니다. 저는 라즈베리 파이 4B 두 대와 오래된 미니 PC 한 대를 이용해서 클러스터를 만들어봤어요. OS는 모두 Ubuntu Server 22.04 LTS를 사용했습니다. 여러분도 리눅스(Linux) 기반의 어떤 장비든 준비하시면 됩니다.

    1. k3s 마스터 노드(Server) 설치

    가장 먼저 클러스터의 ‘뇌’ 역할을 할 마스터 노드를 설치합니다. k3s는 정말 설치가 간단해서 명령어 한 줄이면 끝나버려요. 💡 팁: 실제 운영 환경에서는 스크립트 내용을 확인하고 사용하는 것이 좋습니다.

    
curl -sfL https://get.k3s.io | sh -

    이 명령어를 실행하면 k3s가 자동으로 설치되고 서비스로 등록되어 실행됩니다. 설치가 끝나면 제대로 작동하는지 확인해볼까요?

    
sudo k3s kubectl get nodes

    기본적으로 k3s는 자체적으로 제공하는 k3s kubectl 명령어를 사용하도록 설정되어 있어요. 처음엔 조금 어색하지만 익숙해지니 괜찮더라고요. k3s가 정상적으로 설치되었다면 마스터 노드가 Ready 상태로 보일 겁니다. 예를 들면 이런 식이죠:

    
NAME         STATUS   ROLES                  AGE   VERSION
master-node   Ready    control-plane,master   2m    v1.28.3+k3s1

    2. k3s 워커 노드(Agent) 추가

    이제 마스터 노드에 연결할 워커 노드(Agent Node)를 추가해봅시다. 워커 노드 역시 명령어 한 줄로 설치되는데, 다만 마스터 노드와 연결하기 위한 토큰(Token)이 필요해요. 이 토큰은 마스터 노드에서 확인할 수 있습니다.

    
sudo cat /var/lib/rancher/k3s/server/node-token

    이 명령어를 실행하면 긴 문자열이 나올 텐데, 이게 바로 워커 노드를 연결할 때 필요한 토큰입니다. 이 토큰과 마스터 노드의 IP 주소를 알고 있다면, 워커 노드에서 다음 명령어를 실행해주세요. <master-ip> 부분은 마스터 노드의 실제 IP 주소로, <token> 부분은 위에서 확인한 토큰으로 바꿔주셔야 합니다.

    
curl -sfL https://get.k3s.io | K3S_URL=https://<master-ip>:6443 K3S_TOKEN=<token> sh -

    워커 노드 설치 후, 다시 마스터 노드에서 sudo k3s kubectl get nodes 명령어를 실행해보세요. 몇 분 뒤에 워커 노드가 Ready 상태로 보인다면 성공입니다! 🎉

    k3s 마스터 및 워커 노드 구성과 kubectl 환경 설정이 완료된 명령줄 인터페이스 스크린샷입니다.

    3. kubectl 환경 설정으로 편하게 사용하기

    매번 sudo k3s kubectl이라고 치는 게 귀찮으시죠? 저도 그랬거든요. 일반적인 kubectl 명령어를 사용할 수 있도록 환경 설정을 해봅시다. 마스터 노드에서 다음 명령어를 실행하여 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
export KUBECONFIG=~/.kube/config

    마지막 export 명령어는 현재 세션에만 적용되므로, 로그인할 때마다 자동으로 적용되게 하려면 .bashrc나 .zshrc 파일에 추가하는 것이 좋습니다. 이제 kubectl get nodes 명령어를 실행해보세요. 잘 동작할 겁니다!

    ⚠️ k3s 설치 중 만난 난관들 & 해결법

    제가 13년차 엔지니어라고 해도 삽질은 피할 수 없죠! k3s 설치 중 저를 괴롭혔던 몇 가지 문제와 해결법을 공유합니다. 혹시 여러분도 비슷한 문제를 겪는다면 참고가 되셨으면 좋겠어요.

    1. 워커 노드가 연결되지 않는 문제 (방화벽!)

      처음엔 마스터 노드와 워커 노드 간 통신이 안 되는 거예요. kubectl get nodes를 하면 워커 노드가 NotReady 상태로 계속 머물러 있었죠. 알고 보니 방화벽(Firewall) 문제였습니다. Ubuntu Server는 기본적으로 ufw(Uncomplicated Firewall)가 활성화되어 있는 경우가 많거든요. k3s는 기본적으로 6443/tcp 포트를 사용하는데, 이 포트가 막혀있었던 겁니다. 🤯

      해결법: 마스터 노드와 워커 노드 모두에서 필요한 포트를 열어줬습니다.

      
sudo ufw allow 6443/tcp  # k3s API Server
sudo ufw allow 10250/tcp # Kubelet (필수)
sudo ufw reload

      특히 마스터 노드는 워커 노드의 Kubelet과 통신해야 하므로 10250 포트도 열어주는 것이 좋습니다. 이 문제를 해결하고 나니 워커 노드가 바로 Ready 상태로 바뀌더라고요. 역시 네트워크 문제는 언제나 기본부터 체크해야 합니다.

    2. 토큰(Token) 불일치로 인한 연결 실패

      간혹 워커 노드를 추가할 때 K3S_TOKEN 값을 잘못 입력하는 경우가 있어요. 아니면 복사 붙여넣기 할 때 공백이 들어간다거나요. 그럼 당연히 워커 노드가 마스터에 연결되지 않습니다.

      해결법: 워커 노드에서 k3s 서비스를 중지하고 삭제한 후, 정확한 토큰 값으로 다시 설치했습니다.

      
sudo systemctl stop k3s-agent
sudo systemctl disable k3s-agent
sudo k3s-uninstall.sh # 워커 노드에 설치된 k3s 삭제 스크립트
# 정확한 토큰으로 다시 설치
curl -sfL https://get.k3s.io | K3S_URL=https://<master-ip>:6443 K3S_TOKEN=<correct-token> sh -

    3. 로그 확인의 중요성

      어떤 문제가 발생하든, 가장 먼저 해야 할 일은 로그를 확인하는 것입니다. k3s 서비스의 로그는 journalctl 명령어를 통해 볼 수 있어요.

      
sudo journalctl -u k3s --since "10 minutes ago" -f
# 워커 노드는
sudo journalctl -u k3s-agent --since "10 minutes ago" -f

      로그를 보면 에러 메시지나 경고 메시지를 통해 문제의 원인을 파악할 수 있는 경우가 많습니다. 저는 방화벽 문제도 로그에서 connection refused 같은 메시지를 보고 눈치챘거든요.

    🎉 완성! k3s 클러스터에 애플리케이션 배포하기

    클러스터가 성공적으로 구축되었다면, 이제 간단한 애플리케이션을 배포해서 잘 동작하는지 확인해봐야죠. 저는 웹 서버로 유명한 Nginx(엔진엑스)를 배포해볼게요. 다음 YAML 파일을 nginx-deployment.yaml로 저장합니다.

    
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: NodePort

    저장한 파일을 클러스터에 배포합니다.

    
kubectl apply -f nginx-deployment.yaml

    배포가 성공적으로 완료되었다면, 파드(Pod)와 서비스(Service)가 잘 생성되었는지 확인해봅시다.

    
kubectl get pods -o wide
kubectl get svc

    kubectl get svc 결과에서 nginx-service의 NodePort를 확인해보세요. 예를 들어 30000번대 포트가 할당될 겁니다. 이제 워커 노드의 IP 주소와 할당된 NodePort를 이용하여 웹 브라우저에서 Nginx 웹 페이지에 접속할 수 있습니다. 예를 들어, http://<워커-노드-IP>:<NodePort> 이런 식으로요. 드디어 제 홈랩 k3s 클러스터에서 Nginx가 동작하는 걸 보니 정말 뿌듯하더라고요! 🎉

    k3s 클러스터에 Nginx 애플리케이션 배포 후 웹 브라우저 접속 화면 및 kubectl 명령 결과를 보여주는 스크린샷입니다.

    🚀 13년차 엔지니어의 제언: k3s 경량 쿠버네티스 활용처

    k3s를 직접 구축하고 사용해보니, 이 경량 쿠버네티스가 얼마나 유용한지 다시 한번 깨달았습니다. 제가 생각하는 k3s의 주요 활용처는 다음과 같습니다.

    활용 분야 k3s의 장점 예시
    홈랩 (Home Lab) 저렴한 비용으로 쿠버네티스 학습 및 개인 서비스 운영 라즈베리 파이 클러스터, 개인 웹서버, 미디어 서버
    엣지 컴퓨팅 (Edge Computing) 제한된 리소스 환경에서 컨테이너 애플리케이션 배포 및 관리 스마트 팩토리, 스마트 시티 IoT 게이트웨이, 지점 서버
    개발/테스트 환경 로컬 머신이나 가상 머신에 빠르고 가볍게 k3s 클러스터 구축 CI/CD 파이프라인 테스트, 개발자 개인 환경
    IoT (사물 인터넷) 수많은 IoT 디바이스의 애플리케이션 배포 및 업데이트 관리 자율주행 차량, 스마트 농장 센서 데이터 처리

    k3s는 쿠버네티스의 복잡성을 줄여주면서도 강력한 기능을 제공하기 때문에, 위와 같은 환경에서 컨테이너 기반 애플리케이션을 효율적으로 배포하고 관리하는 데 탁월한 선택이 될 수 있습니다. 저처럼 인프라를 직접 만져보고 실험하는 걸 좋아하는 분들에게는 정말 최고의 장난감이 될 거예요. 💡

    물론 k3s가 모든 상황에 완벽한 만능 해결책은 아니에요. 대규모 엔터프라이즈 환경에서는 여전히 표준 쿠버네티스 배포판이 더 적합할 수 있습니다. 하지만 소규모, 리소스 제한 환경에서는 k3s가 제공하는 가치는 엄청나다고 생각합니다. 저도 처음엔 ‘이 작은 걸로 뭘 할 수 있을까?’ 싶었는데, 지금은 제 홈랩의 핵심 인프라가 되었습니다. 다음 글에서는 k3s 위에 Helm(헬름)으로 애플리케이션을 배포하거나 Persistent Storage(영구 스토리지)를 구성하는 방법에 대해서도 다뤄볼 예정이니 기대해주세요!

    k3s의 주요 장점과 활용 사례를 간결하게 요약한 인포그래픽입니다.

    오늘 제가 공유한 삽질 경험과 해결 과정이 여러분의 k3s 경량 쿠버네티스 클러스터 구축에 조금이나마 도움이 되었기를 바랍니다. 혹시 궁금한 점이나 또 다른 삽질 경험이 있다면 언제든지 댓글로 남겨주세요! 13년차의 서버실은 언제나 열려있습니다. 다음 글에서 또 만나요! 👋

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

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