~/dasomel
한국어
← Back

Narwhal

Vagrant-based Kubernetes Internal Developer Platform (IDP) cluster

GitHub
Kubernetes
Vagrant
GitOps
IDP
Istio
ArgoCD
Cilium

Project Overview

Narwhal is a Vagrant-based Kubernetes Internal Developer Platform (IDP) cluster.

Like the narwhal — the "unicorn of the sea" — it delivers a powerful full platform in a single cluster. Built on the kube-ready-box dasomel/ubuntu-26.04-xfs Box, it fully automates provisioning of a Kubernetes v1.35 HA cluster with GitOps, SSO, Observability, Service Mesh, Storage, and Backup.

Key Components

LayerComponents
OrchestrationKubernetes v1.35 (HA: 3 masters, 3 workers)
NetworkingCilium CNI, MetalLB, kube-vip (VIP HA), APISIX API Gateway
GitOpsArgoCD + Gitea (App-of-Apps pattern)
SSOKeycloak OIDC (ArgoCD, Grafana, Gitea, Harbor, Headlamp)
ObservabilityPrometheus, Grafana, Loki, Tempo, Hubble
StorageNFS (Block) + SeaweedFS (Object/S3) + nfs-quota-agent
Service MeshIstio ambient mode (mTLS, ztunnel, zero sidecars)
Securitycert-manager, OpenBao (Secrets), Kyverno (Policy)
BackupVelero + CNPG barman
TestingChaos Mesh (chaos experiments), k6 (load testing)

Architecture

┌──────────────────────────────────────────────────┐
│                  Vagrant VMs                     │
├──────────────────┬─────────────┬─────────────────┤
│  master-1        │ master-2/3  │ worker-1/2/3    │
│  192.168.56.10   │ .11 / .12   │ .21 / .22 / .23 │
│  2 CPU, 6GB      │ 2 CPU, 6GB  │ 2 CPU, 6GB      │
│  NFS, dnsmasq    │ dnsmasq     │                 │
└──────────────────┴─────────────┴─────────────────┘
                   VIP: 192.168.56.100 (kube-vip)
                   LB:  192.168.56.200 (MetalLB/APISIX)
                   DNS: *.local.narwhal.internal

Requirements

  • Vagrant 2.4+
  • VirtualBox 7.1+ or VMware Fusion 26H1
  • 32GB+ RAM (40GB+ recommended)
  • 30GB+ Disk per VM

Quick Start

git clone https://github.com/dasomel/narwhal.git
cd narwhal
 
# Create cluster (all components auto-provisioned)
vagrant up --provider=vmware_desktop
 
# Check node status
vagrant ssh master-1 -c "kubectl get nodes"
 
# Destroy cluster
vagrant destroy -f

Technical Documentation

Detailed write-ups of each area, sourced directly from the cluster repository.

DocumentContents
ArchitectureCluster topology, HA control plane, node layout
NetworkingCilium, MetalLB, kube-vip, APISIX, DNS
GitOpsArgoCD + Gitea App-of-Apps pattern
Security & SSOKeycloak OIDC, OpenBao, Kyverno, cert-manager
ObservabilityPrometheus, Grafana, Loki, Tempo, Hubble
Storage & DatabaseNFS, SeaweedFS, nfs-quota-agent, CNPG
Operations & Disaster RecoveryDay-2 ops, Velero backup/restore, incident response
Testing & Chaos EngineeringChaos Mesh experiment suite, k6 load tests, baselines

References