프로젝트 소개

Kube-Ready-Box는 Kubernetes를 로컬 VM 환경에서 빠르게 부트스트랩하기 위한 Ubuntu Vagrant Base Box 프로젝트입니다.

이 프로젝트의 핵심은 Kubernetes 자체를 포함하는 것이 아니라, Kubernetes가 올라가기 전에 필요한 **운영체제 수준의 준비 상태(OS readiness)**를 하나의 재현 가능한 이미지로 만드는 것입니다.

현재 Ubuntu 24.04 LTS와 26.04 LTS를 제공하며, ext4와 XFS filesystem variant를 분리합니다. Apple Silicon 환경을 포함한 ARM64와 AMD64를 지원하고 VirtualBox와 VMware Fusion 같은 로컬 hypervisor에서 사용할 수 있습니다.

Kube-Ready-Box는 Kubernetes installer가 아닙니다. kubelet, kubeadm, kubectl, CNI 및 container runtime은 사용자가 원하는 버전을 선택해 이후 설치합니다.

왜 필요한가

Narwhal, Beluga와 같은 로컬 Kubernetes 프로젝트에서는 VM을 만들 때마다 다음 작업이 반복됩니다.

Ubuntu Cloud Image
      ↓
filesystem / disk 준비
      ↓
kernel modules / sysctl
      ↓
network / conntrack / buffers
      ↓
CSI / iSCSI / NFS prerequisite
      ↓
time synchronization
      ↓
monitoring / diagnostics tools
      ↓
Kubernetes bootstrap

Kube-Ready-Box는 이 중 Kubernetes가 요구하는 OS baseline을 이미지 단계에서 표준화합니다. 결과적으로 각 상위 프로젝트는 cluster bootstrap 로직에만 집중할 수 있습니다.

제공 이미지

Vagrant Cloud의 주요 box 이름은 다음과 같습니다.

dasomel/ubuntu-24.04-ext4
dasomel/ubuntu-24.04-xfs
dasomel/ubuntu-26.04-ext4
dasomel/ubuntu-26.04-xfs

Kubernetes Readiness Baseline

이미지는 다음과 같은 OS 수준 준비 작업을 포함합니다.

• swap 비활성화
• Kubernetes에 필요한 kernel modules (br_netfilter, overlay, iscsi_tcp)
• IP forwarding / bridge networking
• conntrack 및 network buffer 튜닝
• /sys/fs/bpf 영구 마운트 (Cilium eBPF 리소스 유지)
• open-iscsi(+iscsid 활성화), cryptsetup, dmsetup — Longhorn V1 요구사항 · nfs-common
• chrony 기반 시간 동기화 — Ubuntu 25.10+/26.04 기본값인 systemd-timesyncd를 대체, 한국 NTP 서버를 /etc/chrony/sources.d/kr-ntp.sources로 사전 구성 (etcd clock-skew 민감성 대응)
• 보안 하드닝: needrestart 제거(Qualys 로컬 권한상승 CVE 5건 대응), unattended-upgrades 완전 purge(kubelet Graceful Node Shutdown 충돌 방지), auditd 설치 후 비활성화(CIS 대응, I/O 제한 포함), apparmor-utils 추가
• jq, yq, network diagnostics, performance tools
• 자동 disk/partition/LVM/filesystem 확장 (1TB thin-provisioned 디스크, box 크기는 ext4 약 2.2GB / XFS 약 3.4GB)

24.04와 26.04의 차이

26.04는 cgroup v2-only 환경이며 containerd/kubelet의 systemd cgroup 설정을 명시적으로 맞춰야 합니다. 반대로 24.04는 보다 보수적인 기본값으로 안정적인 로컬 Kubernetes 개발 환경을 제공합니다.

Build Pipeline

Ubuntu Cloud Image
       ↓
     Packer
       ↓
OS configuration + filesystem tuning
       ↓
provider-specific validation
       ↓
Vagrant Box
       ↓
Vagrant Cloud
       ↓
Narwhal / Beluga / local K8s projects

Packer가 이미지를 생성하고 GitHub Actions가 provider와 architecture별 빌드·검증·배포를 자동화합니다. Box version과 Ubuntu release를 명확히 분리해 상위 프로젝트가 재현 가능한 개발 환경을 선택할 수 있습니다.

Filesystem 선택

ext4

일반적인 Kubernetes 개발 환경과 범용 workload에 적합합니다. Shrink와 일반 Linux tooling 호환성이 필요한 경우 유리합니다.

XFS

대용량 데이터와 Kubernetes storage/quota 실험에 적합합니다. 특히 NFS Quota Agent와 함께 사용할 경우 XFS Project Quota를 활용할 수 있습니다.

시작하기

# 안정적인 기본 이미지
vagrant init dasomel/ubuntu-24.04-ext4
vagrant up --provider=vmware_desktop
 
# XFS / quota 환경
vagrant init dasomel/ubuntu-24.04-xfs
vagrant up --provider=vmware_desktop
 
# Ubuntu 26.04
vagrant init dasomel/ubuntu-26.04-ext4
vagrant up --provider=vmware_desktop

사용 후에는 box 자체가 Kubernetes cluster를 제공하는 것이 아니라는 점을 전제로 containerd, kubelet, kubeadm 또는 원하는 Kubernetes 배포판을 추가합니다.

검증

vagrant ssh -c "cat /etc/vagrant-box/info.json"
vagrant ssh -c "/bin/bash /etc/vagrant-box/check-tuning.sh"

검증 포인트는 단순히 VM이 boot되는지가 아니라, kernel setting, network readiness, filesystem 및 Kubernetes prerequisite가 의도한 baseline과 일치하는지입니다.

현재 상태

최신 릴리스는 v1.1.0(2026-07-19)입니다. Ubuntu 26.04 LTS(Resolute Raccoon, kernel 7.0)를 24.04 LTS(Noble Numbat, 기본값)와 함께 정식 태그로 배포하는 첫 릴리스이며, 위 보안 하드닝과 chrony 전환, CSI/Longhorn 전제조건, bpffs 영구 마운트가 이 릴리스에서 추가됐습니다.

• 별도 프로젝트로 선언형 NixOS 변형 dasomel/nixos-kube-ready(libvirt/arm64, Apple Silicon은 vagrant-qemu 경유)도 배포됩니다.
• Packer 1.10+ (CI는 1.15.4 고정), 빌드 타임아웃은 ssh_timeout 1시간(vmware-arm64는 2시간), CI job 타임아웃 90분입니다.

상세 기술 문서

프로젝트 관계