WORK / ACTIVE SYSTEM

Kube-Ready-Box

Kubernetes를 위한 Ubuntu 24.04/26.04 LTS Vagrant Base Box · ARM64/AMD64 · ext4/XFS

Kubernetes · Vagrant · Packer · Ubuntu · ARM64 · AMD64 · XFS · ext4 · VMware · VirtualBox
01 / Problem02 / Architecture03 / Development04 / Proof05 / Knowledge06 / Record
01 / PROBLEM

로컬 Kubernetes 클러스터를 반복해서 만들 때 OS 튜닝, kernel modules, networking, storage prerequisites를 매번 준비해야 하고 ARM64/AMD64와 provider별 차이까지 별도로 관리해야 함

RESPONSE

Packer로 Kubernetes용 Ubuntu base image를 사전 구성하고 GitHub Release와 GitHub Pages 카탈로그로 배포해 동일한 OS baseline을 여러 로컬 클러스터 프로젝트에서 반복 사용

02 / ARCHITECTURE

기능보다 먼저 경계와 연결을 봅니다.

Identity, Delivery, Network, Storage, Workload 통합을 기능 목록이 아니라 운영 경계로 읽습니다.

03 / DEVELOPMENT OVER TIME

계속 발전하는 과정도 evidence입니다.

첫 commit, 누적 commit, release와 최근 활동으로 시스템이 지금도 개발되고 있는지 보여줍니다.

DEVELOPMENT OBSERVATORY
dasomel/kube-ready-box

한 번 만든 결과가 아니라, 시간에 따라 계속 발전하는 시스템을 봅니다.

Contributors: 3
첫 commit
2026년 1월 22일
누적 commits
407
Releases
12
최신 release
v0.3.5
최근 push
2026년 11월 22일
개발 기간
10개월
최근 개발 활동
311 commits / 20 weeks
PAST → NOW
언어: Shell라이선스: MITStars: 1Forks: 0Open issues: 18최신 release
04 / PROOF, NOT BADGES
10
technology / domain signals

Declared scope and technical context

6
connected docs

Operational or implementation documentation

2
engineering notes

Knowledge produced by the project

0
digest links

External signals explicitly connected

06 / ENGINEERING RECORD

구현 세부사항, 운영 기록과 프로젝트별 맥락을 이어서 봅니다.

프로젝트 소개

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 bootstrap

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

제공 이미지

UbuntuFilesystem주요 용도
24.04 LTSext4기본 안정형 로컬 Kubernetes 노드
24.04 LTSXFSstorage/quota 및 대용량 workload
26.04 LTSext4최신 LTS / cgroup v2-only 환경
26.04 LTSXFS최신 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-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 확장 (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.04Ubuntu 26.04
Kernel6.87.0
cgroupv2 기본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 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를 활용할 수 있습니다.

시작하기

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_desktop

XFS / 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로 옮겼습니다.

ProviderAMD64ARM64비고
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_timeout 1시간(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

프로젝트 관계

Architecture diagram
Responsive vector rendering · source preserved
kube-ready-box ↓ local Kubernetes node baseline Narwhal Beluga KubeMetal / other K8s projects ↓ higher-level platform