프로젝트 소개

Narwhal Portal은 Narwhal Kubernetes Internal Developer Platform을 위한 중앙 관리 포털입니다. Narwhal이 Kubernetes, GitOps, SSO, Observability, Storage, Security와 같은 플랫폼 구성요소를 제공한다면, Portal은 사용자가 그 플랫폼을 실제로 이해하고 운영하기 위한 **통합 운영면(Operational Surface)**을 제공합니다.

포털은 특정 OSS 화면을 복제하는 대신, 플랫폼의 여러 신호를 하나의 사용자 경험으로 묶는 데 초점을 둡니다. 클러스터 상태, Argo CD 애플리케이션, 노드, 보안, 비용, 거버넌스, 서비스 카탈로그와 같은 정보는 각각의 원천 시스템을 기준으로 하되, 사용자가 문제의 위치와 다음 행동을 빠르게 파악할 수 있도록 중앙화합니다.

핵심 기능

플랫폼 내 위치

                    Narwhal IDP
┌───────────────────────────────────────────────────────┐
│ Kubernetes                                             │
│ GitOps · SSO · Observability · Storage · Security      │
└─────────────────────────┬─────────────────────────────┘
                          │ platform APIs / cluster state
                          ▼
                ┌──────────────────────┐
                │   Narwhal Portal     │
                │   Next.js + React    │
                ├──────────────────────┤
                │ Dashboard            │
                │ Catalog / My Apps     │
                │ Nodes / Cost          │
                │ Security / Governance│
                │ Architecture / Tools │
                └──────────┬───────────┘
                           │
                           ▼
                 Developer / Operator

Portal은 Narwhal 클러스터와 분리된 별도 제품이 아니라 Narwhal 플랫폼의 day-2 운영 및 개발자 경험 계층입니다. 따라서 Narwhal과 함께 사용할 때 가장 큰 가치가 발생합니다.

기술 스택

• Next.js 16 / React 19 — App Router 기반 포털 애플리케이션
• TypeScript — UI와 API 경계의 타입 안전성
• Tailwind CSS 4 / shadcn/ui — 재사용 가능한 관리 화면 구성
• TanStack Query / Zustand — 서버 상태와 클라이언트 상태 관리
• Keycloak OIDC — 인증 및 플랫폼 사용자 세션 통합
• Valkey — 애플리케이션 캐시 계층
• OpenBao Agent Injector — 런타임 Secret 주입
• Skaffold / Kaniko — Kubernetes 기반 inner-loop 개발과 클러스터 내부 이미지 빌드

개발 및 배포 모델

# 로컬 개발
git clone https://github.com/dasomel/narwhal-portal.git
cd narwhal-portal
pnpm install
pnpm dev

운영 환경에서는 Narwhal 클러스터 내부에서 APISIX Gateway를 통해 https://portal.local.narwhal.internal로 제공됩니다. 일반적인 배포는 로컬 Docker 데몬에 의존하지 않고 Gitea → Kaniko → Harbor 흐름을 사용할 수 있으며, Skaffold 기반 HMR 개발 경로도 제공합니다.

설계 원칙

1. 원천 시스템은 계속 authoritative

Argo CD, Kubernetes, Keycloak 등 각 시스템이 소유한 상태를 Portal이 복제해 새로운 source of truth로 만들지 않습니다. Portal은 원천 상태를 조회하고 사용자에게 필요한 상관관계와 운영 맥락을 제공합니다.

2. 플랫폼 용어로 묶기

사용자가 각각의 OSS 제품 이름을 이해해야만 플랫폼을 운영할 수 있도록 만들지 않고, Application, Node, Service, Catalog, Security, Governance 같은 플랫폼 개념으로 표현합니다.

3. 운영 경계를 UI에 노출

권한, 인증서, GitOps ownership, 정책 위반, 장애 상태와 같은 제약조건을 숨기지 않고 운영 화면에 드러내어 잘못된 조작을 줄입니다.

4. 개발자 경험과 운영자 경험의 결합

Portal은 단순 관리자 Dashboard가 아니라 Onboarding, Catalog, Templates, Tools를 포함해 Day-0부터 Day-2까지 연결되는 IDP Workbench를 지향합니다.

상세 기술 문서

프로젝트 관계

kube-ready-box
       ↓
   Narwhal Cluster
       ├── GitOps / SSO / Observability / Storage / Security
       │
       └── Narwhal Portal
              ↓
       Developer / Operator UX