Project Overview
Narwhal Portal is the management portal and developer workbench for the Narwhal Kubernetes Internal Developer Platform.
Narwhal provides the underlying GitOps, SSO, observability, storage, security, and platform services. The Portal provides the day-2 operational surface that makes those services understandable and usable as one platform.
The portal does not try to replace every upstream UI. Kubernetes, Argo CD, Keycloak, and other systems remain authoritative; the Portal aggregates platform signals and exposes them through platform-level concepts.
Core Areas
| Area | Purpose |
|---|---|
| Dashboard | Cluster health, Argo CD applications, alerts, and overall platform status |
| Onboarding | Getting-started workflow and kubeconfig issuance |
| Catalog / My Apps | Service catalog and per-user application view |
| Nodes | Node inventory and status |
| Cost | Namespace/workload cost visibility |
| Security / Compliance | Security posture, policies, RBAC, and audit-related information |
| Governance | Scorecards, DORA-related information, and platform maturity signals |
| Architecture | Platform and service relationships |
| Templates / Tools | Developer-oriented platform utilities |
| Settings | Users, routes, certificates, and policy settings |
Position in Narwhal
Technology Stack
- Next.js
^16.3.1/ React19.2.8— App Router application - TypeScript
^6.0.3— typed frontend/API boundaries - Tailwind CSS
4.3.3/ shadcn/ui — reusable admin UI - TanStack Query / Zustand — server/client state
- NextAuth
5.0.0-beta.30+ Keycloak OIDC — authentication and sessions - Valkey — application cache (a dedicated pub/sub client keeps long-lived subscriptions apart from the fail-fast cache client's short timeout/retry limits)
- OpenBao Agent Injector — runtime secrets injection
- Skaffold / Kaniko — Kubernetes inner-loop development and in-cluster image builds
- Vitest — unit/regression suite wired into CI. Playwright-based browser-level e2e coverage is still planned, not claimed as implemented on main (
docs/IMPLEMENTATION-STATUS.md, last verified 2026-09-14) - pnpm
10.27.0(pinned viapackageManager)
Current Status
The dasomel/narwhal-portal repository is archived, and the portal code now lives in the portal/ directory of dasomel/narwhal (per the archived repository README: the 415-commit history was imported with git-filter-repo, and open issues were transferred to narwhal #356-#382). Versions are tracked as portal/vX.Y.Z tags in the narwhal repository; GitHub Releases titled "Portal v1.1.x" start at v1.1.1. The container image name stays ghcr.io/dasomel/narwhal-portal.
The latest release is Portal v1.1.2 (portal/v1.1.2, 2026-10-26).
- v1.1.2 (2026-10-26): fixed the Architecture > Cluster infrastructure view showing 0 nodes, pods and namespaces on production (it now reads the in-cluster projected service-account token file, narwhal#475) and upgraded
zodandundicipast published advisories - v1.1.1 (2026-10-23): security patch upgrading Auth.js (
next-auth5.0.0-beta.32,@auth/core^0.41.3) past critical advisories, plus Next.js 16.4.2 and React 19.3.1. An OAuth login in flight during the rollout fails once and must be retried - v1.1.0 (2026-10-15, tag only, no GitHub Release): first version cut from the monorepo. Production now requires authenticated Valkey TLS, OpenBao auth mode must be explicit, and write routes distinguish rejected, credential and outcome-unknown results so provider failures are no longer reported as healthy. Tags 1.0.18 and 1.0.19 were pushed but never published as GitHub Releases, so v1.1.0 covers everything since 1.0.17
The last release of the old repository is v1.0.17 (2026-08-09). The narwhal v1.3.0 GitOps chart pins the portal image to 1.1.0, and the chart on main pins 1.1.2.
Deployment Model
The production portal is served inside the Narwhal cluster at https://portal.local.narwhal.internal through the APISIX gateway.
A local development loop is available with:
git clone https://github.com/dasomel/narwhal.git
cd narwhal/portal
pnpm install
pnpm devFor cluster-based development, the project also supports Skaffold HMR. Production image workflows can use the in-cluster Gitea → Kaniko → Harbor path, avoiding a local Docker daemon for the normal deployment flow.
Design Principles
Preserve authoritative sources
Argo CD, Kubernetes, Keycloak, and other platform services keep ownership of their resources. The Portal is a user-facing integration layer, not a competing source of truth.
Use platform domains
Users should not need to understand every upstream product to answer platform questions. Concepts such as Application, Service, Catalog, Security, and Governance create a consistent IDP vocabulary.
Expose operational boundaries
GitOps ownership, policy violations, authentication state, certificate state, and failure conditions should be visible in the UI rather than hidden behind an upstream product boundary.
Connect Day-0 and Day-2
Onboarding, Catalog, Templates, Tools, and operational dashboards are part of the same workbench so the portal spans from initial access to ongoing operations.
Documentation Index
| Topic | Document | Purpose |
|---|---|---|
| Overview | Portal Overview | Role and user scenarios |
| Architecture | Portal Architecture | Application/data flow |
| Getting Started | Development Setup | pnpm, environment, Skaffold |
| Operations | Deployment & Operations | Build, deployment, health |
| ADR | Architecture Decision Records | Technical decisions and trade-offs |