프로젝트 소개
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용 템플릿을 제공합니다. 최신 릴리스(v0.3.1)는 Ubuntu 박스를 arm64(vmware_desktop)와 amd64(virtualbox)로 배포합니다(자세한 내용은 현재 상태 참고).
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 bootstrapKube-Ready-Box는 이 중 Kubernetes가 요구하는 OS baseline을 이미지 단계에서 표준화합니다. 결과적으로 각 상위 프로젝트는 cluster bootstrap 로직에만 집중할 수 있습니다.
제공 이미지
| Ubuntu | Filesystem | 주요 용도 |
|---|---|---|
| 24.04 LTS | ext4 | 기본 안정형 로컬 Kubernetes 노드 |
| 24.04 LTS | XFS | storage/quota 및 대용량 workload |
| 26.04 LTS | ext4 | 최신 LTS / cgroup v2-only 환경 |
| 26.04 LTS | XFS | 최신 LTS + project quota 활용 |
Ubuntu 외에 Rocky 9(ext4/XFS, 0.1.1)와 NixOS(nixos-kube-ready, 0.2.2, libvirt)도 같은 카탈로그에서 제공합니다. 배포 카탈로그(GitHub Pages)의 box 이름은 다음과 같습니다.
ubuntu-24.04-ext4 ubuntu-24.04-xfs
ubuntu-26.04-ext4 ubuntu-26.04-xfs
rocky-9-ext4 rocky-9-xfs
nixos-kube-ready.box 파일은 GitHub Release asset으로, Vagrant catalog JSON은 GitHub Pages로 제공합니다. 자세한 내용은 box-distribution.md를 참고하세요.
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-commonchrony기반 시간 동기화 — 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 확장 (box 크기는 1–2 GiB, root LV는 설치 시 16 GiB이며 첫 부팅 때 전체 디스크로 확장)
24.04와 26.04의 차이
26.04는 cgroup v2-only 환경이며 containerd/kubelet의 systemd cgroup 설정을 명시적으로 맞춰야 합니다. 반대로 24.04는 보다 보수적인 기본값으로 안정적인 로컬 Kubernetes 개발 환경을 제공합니다.
| 항목 | Ubuntu 24.04 | Ubuntu 26.04 |
|---|---|---|
| Kernel | 6.8 | 7.0 |
| cgroup | v2 기본 | v2-only |
| 기본 선택 | 안정성 중심 | 최신 커널/플랫폼 기능 |
| Kubernetes 주의점 | 일반적인 설정 | SystemdCgroup=true 확인 |
Build Pipeline
Ubuntu Cloud Image
↓
Packer
↓
OS configuration + filesystem tuning
↓
provider-specific validation
↓
Vagrant Box
↓
GitHub Release (.box) + GitHub Pages (catalog JSON)
↓
Narwhal / Beluga / local K8s projectsPacker가 이미지를 생성하고 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를 활용할 수 있습니다.
시작하기
Vagrantfile에 box 이름과 catalog URL을 지정합니다.
config.vm.box = "dasomel/ubuntu-24.04-ext4"
config.vm.box_url = "https://dasomel.github.io/kube-ready-box/boxes/ubuntu-24.04-ext4.json"vagrant up --provider=vmware_desktopXFS / quota 환경이나 Ubuntu 26.04는 box 이름과 catalog JSON을 ubuntu-24.04-xfs, ubuntu-26.04-ext4 등으로 바꿔 사용합니다.
과거에 Vagrant Cloud에서 1.1.0을 받았다면 Vagrant가 1.1.0을 0.3.x보다 높은 버전으로 취급하므로 먼저
vagrant box remove dasomel/<box> --box-version 1.1.0을 실행하세요.
사용 후에는 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과 일치하는지입니다.
현재 상태
최신 릴리스는 v0.3.1(2026-11-02)입니다. Ubuntu 박스만 다시 빌드해, 설치기가 GRUB에 남긴 커널 인자(autoinstall ds=nocloud-net;s=http://<빌드 호스트>/)와 업그레이드 뒤 남은 설치용 커널 잔재를 지웠습니다. 릴리스 직후 Trivy 스캔도 Ubuntu 4종 모두 수정 가능 CVE 0건입니다. 2026-11-03에는 같은 v0.3.1에 Ubuntu VirtualBox amd64 박스 4종을 추가했습니다. GitHub x86 러너에서 빌드하고 같은 러너에서 VirtualBox로 부팅 검증을 통과한 것만 올렸으며, 스캔 결과도 수정 가능 CVE 0건입니다.
그 전 v0.3.0(2026-11-01)은 CVE 재빌드 릴리스로, 릴리스 시점 Trivy 기준 모든 박스의 배포판 수정 가능 CVE가 0건입니다(이전 Rocky 9 0.1.0 계열은 438건(critical 5), 미배포 Ubuntu 26.04 빌드는 1,141건(critical 2)). 커널 CVE-2026-98432는 Ubuntu/Rocky 모두 아직 수정이 없어 security-response.md에서 추적합니다.
버전은 Ubuntu 박스 0.3.1, Rocky 9 박스 0.1.1, NixOS 박스 0.2.2(libvirt)입니다. Ubuntu 버전 라인은 초기화됐는데, 1.1.0은 Vagrant Cloud에만 올라간 버전이기 때문입니다. 위 보안 하드닝과 chrony 전환, CSI/Longhorn 전제조건, bpffs 영구 마운트는 그대로 포함됩니다.
HashiCorp가 HCP Vagrant(Vagrant Cloud)를 종료합니다. 신규 box/registry 생성은 2026-10-01에 중단됐고, 지원은 2026-11-02에 종료되며, 호스팅된 모든 box는 2026-12-31에 폐기됩니다(공지). 그래서 배포 채널을 GitHub Release와 GitHub Pages로 옮겼습니다.
| Provider | AMD64 | ARM64 | 비고 |
|---|---|---|---|
| VirtualBox | ✅ (Ubuntu) | 템플릿만* | AMD64는 GitHub x86 러너에서 빌드·부팅 검증; ARM64는 VirtualBox 7.1+ 필요, *빌드 호스트에서 VirtualBox SSH를 검증할 수 없어 미배포 |
| VMware Fusion | 템플릿만* | ✅ | Apple Silicon 지원; *AMD64는 러너에서 VMware를 돌릴 수 없어 미배포 (로컬 빌드는 가능) |
- Ubuntu는
vmware_desktop(arm64)과virtualbox(amd64), Rocky는vmware_desktop(arm64), NixOS는libvirt(arm64) 박스를 배포합니다. Intel/AMD 호스트에서는vagrant up --provider virtualbox로 씁니다. - 별도 변형인 선언형 NixOS 박스
dasomel/nixos-kube-ready(libvirt/arm64, Apple Silicon은vagrant-qemu경유)도 같은 카탈로그에서 배포됩니다. - Packer 1.10+ (CI는 1.15.4 고정), 빌드 타임아웃은
ssh_timeout1시간(vmware-arm64는 2시간), CI job 타임아웃 90분입니다.
상세 기술 문서
| 주제 | 문서 | 내용 |
|---|---|---|
| Overview | 박스 개요 | 프로젝트 목적과 지원 범위 |
| Architecture | 시스템 구조 | Packer → Box → Vagrant 흐름 |
| Getting Started | 사용 가이드 | provider와 filesystem 선택 |
| Operations | 빌드/릴리스 | Packer와 GitHub Release/Pages 배포 |
| Verification | 검증 | OS readiness와 release validation |