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.

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 263 documented incidents and 51 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