Narwhal

Project Overview

Narwhal is an open-source Internal Developer Platform (IDP) built around Kubernetes. It combines GitOps, IAM/SSO, service mesh, observability, registry, storage, backup, policy, API gateway, and management portal capabilities into one reproducible platform unit.

Narwhal is not primarily a Kubernetes installer. Its product boundary is the integration seam between independently developed projects.

Current Scale

These numbers are engineering evidence of repeated integration and verification, not simply activity metrics.

Current Status

The latest tagged release is v1.2.0 (2026-08-09), which turned air-gapped installation from "images only" into an install that genuinely completes with no route to the internet. It promoted Kakao Cloud to a first-class OpenTofu-provisioned provider and added a Chaos Mesh 2.8.3 + k6 load-test suite plus a 36-check clean-install regression suite in CI.

Since v1.2.0, main has accumulated further security hardening that is not yet in a tagged release (verified against the commit history as of 2026-09-23):

• Enforced Keycloak OIDC TLS verification and internal CA trust; removed ArgoCD/APISIX OIDC TLS bypasses
• Restricted the APISIX Admin API allowlist to the cluster pod CIDR
• Enforced SSH host-key verification on Kakao bastion/node paths and split the bastion security group from the node security group
• Switched the default NFS export to root_squash with a non-world-writable root
• Added a default-deny NetworkPolicy for the database namespace and a Kyverno admission gate for the node-tuning job service account
• Narrowed the portal's OpenBao access to least privilege, removing unnecessary secret/data/* grants

This work is release-candidate material still under verification on main, not yet part of a published tag.

Platform Components

Kubernetes and networking

• Kubernetes v1.35
• Cilium v1.19.x
• Hubble v1.19.x
• kube-vip v1.1.x
• MetalLB v0.16.x
• Apache APISIX 3.15.x

GitOps and identity

• Argo CD v3.4.x
• Gitea v1.26.x
• Keycloak 26.5.x

Observability

• Prometheus Stack v0.91.x
• Loki 3.7.x
• Grafana Alloy v1.17.x
• Tempo 2.9.x
• Hubble

Platform services

• Harbor v2.15.x
• OpenBao v2.5.x
• Kyverno v1.18.x
• Headlamp v0.42.x
• SeaweedFS v4.34.x
• Velero v1.18.x
• CloudNative-PG v1.29.x
• Istio v1.30.x in ambient mode

Integration Seams as Product

A typical identity-to-application path crosses several independent systems:

Keycloak OIDC
      ↓
APISIX authentication
      ↓
service routing
      ↓
Istio ambient / ztunnel
      ↓
Kubernetes workload

Narwhal records the assumptions at these boundaries as documentation, scripts, health checks, and regression checks so they can be revalidated during upgrades.

Knowledge as Tests

The core maintenance loop is:

Incident
   ↓
Root Cause
   ↓
Discriminator
   ↓
Regression Check
   ↓
Upgrade Gate

The incident log records not only what fixed an incident, but also how to distinguish it from similar failures and which tempting fixes do not work. This knowledge base is connected to the regression suite, producing 318 documented incidents and 192 CI checks.

Verification Model

Narwhal validates different layers for different questions.

This separation keeps fast CI regression checks independent from deeper live-cluster validation.

Air-Gapped Installation

Disconnected installation is a first-class deployment target.

Online build
   ↓
images / charts / binaries / manifests / packages
   ↓
architecture-specific offline bundle
   ↓
verification
   ↓
install without live Internet

The bundle contains the artifacts required to reproduce the platform without reaching upstream registries during installation.

Management Portal

Narwhal Portal provides the day-2 user experience for the platform: dashboard, applications, security, cost, governance, catalog, and architecture views.

The product boundary is therefore:

Narwhal = platform integration + operation
Portal  = developer / operator experience

Getting Started

git clone https://github.com/dasomel/narwhal.git
cd narwhal
vagrant up --provider=vmware_desktop
vagrant ssh master-1 -c "kubectl get nodes"
vagrant ssh master-1 -c "kubectl get applications -A"
vagrant ssh master-1 -c "bash /home/vagrant/scripts/test/verify-cluster.sh"

Documentation Index

Project Relationship