dasomel
EN
전체 시스템
WORK / ACTIVE SYSTEM

Narwhal

재현 가능하고 검증 가능한 Kubernetes Internal Developer Platform

Kubernetes · Vagrant · GitOps · IDP · Istio Ambient · Argo CD · Cilium · Air-Gap · Keycloak · Observability
Source
01 / Problem02 / Architecture03 / Development04 / Proof05 / Knowledge06 / Record
01 / PROBLEM

수십 개 Cloud Native 프로젝트를 개별적으로 설치하면 DNS, TLS, identity, networking, startup order, version compatibility 같은 integration seam에서 반복적인 장애가 발생하고 업그레이드 때 다시 검증해야 함

RESPONSE

35개 GitOps-managed application을 하나의 reproducible IDP로 통합하고, 263건의 incident knowledge를 51개 CI regression checks와 live verification suite로 연결

02 / ARCHITECTURE

기능보다 먼저 경계와 연결을 봅니다.

Identity, Delivery, Network, Storage, Workload 통합을 기능 목록이 아니라 운영 경계로 읽습니다.

Narwhal architecture: developer portal through APISIX and Keycloak to Argo CD/Gitea, HA Kubernetes and platform services
Narwhal platform map — identity, GitOps, Kubernetes and integrated platform services.
ARCHITECTURE / HOW IT WORKS

Narwhal Internal Developer Platform

01
Developer / Operator
Portal · service access
02
APISIX + Keycloak
Gateway · OIDC · SSO
03
Argo CD + Gitea
GitOps app-of-apps
04
Kubernetes HA
Cilium · Istio ambient · kube-vip
05
Platform Services
Observability · storage · backup · policy
Developer access flows through gateway and identity into GitOps-managed Kubernetes, with platform services operated as one integrated system.
PLATFORM MAP / VISUAL EVIDENCE

One login, one GitOps path, many platform capabilities

01
Portal + Keycloak SSO
02
Argo CD + Gitea GitOps
03
Cilium + Istio + APISIX
04
Prometheus · Loki · Tempo · Hubble
A compact visual summary; the architecture diagram below explains the execution flow in more detail.
03 / DEVELOPMENT OVER TIME

계속 발전하는 과정도 evidence입니다.

첫 commit, 누적 commit, release와 최근 활동으로 시스템이 지금도 개발되고 있는지 보여줍니다.

DEVELOPMENT OBSERVATORY
dasomel/narwhal

한 번 만든 결과가 아니라, 시간에 따라 계속 발전하는 시스템을 봅니다.

Contributors: 3
첫 commit
2026년 2월 8일
누적 commits
573
Releases
4
최신 release
v1.2.0
최근 push
2026년 9월 11일
개발 기간
7개월
최근 개발 활동
493 commits / 20 weeks
PAST → NOW
언어: Shell라이선스: Apache-2.0Stars: 0Forks: 1Open issues: 138최신 release
04 / PROOF, NOT BADGES
35
GitOps-managed applications

Desired platform state under GitOps

51
CI regression checks

Integration behavior protected in CI

263
integration / incident lessons

Failures retained as engineering knowledge

120+
cluster checks

Repeatable platform verification

05 / CONNECTED KNOWLEDGE

코드 밖에 남은 엔지니어링 지식

06 / ENGINEERING RECORD

구현 세부사항, 운영 기록과 프로젝트별 맥락을 이어서 봅니다.

프로젝트 소개

Narwhal은 Kubernetes 위에 GitOps, IAM/SSO, Service Mesh, Observability, Registry, Storage, Backup, Policy, API Gateway와 Management Portal을 함께 제공하는 오픈소스 **Internal Developer Platform (IDP)**입니다.

Narwhal의 핵심은 Kubernetes 자체를 설치하는 것이 아닙니다. 실제 운영 비용이 발생하는 컴포넌트 사이의 integration seam을 하나의 제품 경계로 다루는 것입니다.

Kubernetes
   ↓
GitOps / Identity / Networking / Security
   ↓
Observability / Storage / Backup / Registry
   ↓
Management Portal
   ↓
Developer / Operator Experience

현재 규모

README 기준 현재 reference implementation은 다음과 같은 상태입니다.

항목현황
Activity2026-02-08 이후 483 commits, 4 releases, latest v1.2.0
Integration35 GitOps-managed applications
Regression51 CI regression checks
Live verificationCluster 120+ checks, SSO 49 checks
Integration knowledge263 documented incidents
DeploymentVagrant ARM64, Kakao Cloud AMD64, air-gapped
Offline bundleArchitecture별 104 container images, 27 Helm charts, binaries, manifests, OS packages

이 수치는 commit 수를 강조하기 위한 것이 아니라, 통합 복잡성을 얼마나 반복해서 검증했는지를 설명하는 운영 증거입니다.

핵심 구성

Kubernetes / Networking

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

GitOps / 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 ambient mode

Integration Seams를 제품으로 보기

예를 들어 다음은 단일 제품의 bug가 아니라 여러 시스템이 연결될 때 발생하는 문제입니다.

Keycloak OIDC claim
       ↓
APISIX authentication
       ↓
service routing
       ↓
Istio ambient mTLS
       ↓
Kubernetes workload

Narwhal에서는 이런 경계를 문서, scripts, health checks, regression checks로 남깁니다. 따라서 특정 설정을 “한번 맞춰 놓는 것”이 아니라 업그레이드마다 다시 검증할 수 있습니다.

Knowledge as Tests

Narwhal의 가장 중요한 운영 자산 중 하나는 lessons-log.md입니다.

장애를 다음과 같이 변환합니다.

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

각 incident에는 원인뿐 아니라 비슷하게 보이는 장애와 구분하기 위한 discriminator와 실패했던 접근까지 기록합니다. 이 방식이 누적되며 263건의 integration knowledge와 51개 CI checks로 연결되었습니다.

검증 계층

Narwhal은 “pod가 Running인가?”만 검증하지 않습니다.

LayerScopeQuestion
Cluster Verification120+클러스터와 플랫폼 application이 실제로 건강한가?
SSO Verification49여러 application의 identity flow가 end-to-end로 동작하는가?
CI Regression51과거에 해결한 integration failure가 다시 발생하지 않았는가?

실제 cluster 검증과 CI 회귀 검증을 분리함으로써 빠른 regression gate와 live environment verification을 동시에 유지합니다.

Air-Gapped Installation

Narwhal은 인터넷 연결이 없는 환경을 중요한 운영 시나리오로 취급합니다.

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

ARM64와 AMD64에 맞는 bundle을 사전에 만들고, upstream artifact identity와 내부 mirror 조건을 포함해 disconnected environment에서도 같은 platform contract를 재현하는 것을 목표로 합니다.

Management Portal

Narwhal은 Narwhal Portal을 함께 사용해 day-2 운영을 제공합니다.

Portal은 dashboard, Argo CD status, security, cost, governance, catalog, architecture 등의 platform-level context를 하나의 UI로 제공합니다.

즉,

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

라는 역할 분리를 유지합니다.

시작하기

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"

지원 환경에는 Vagrant 기반 ARM64/AMD64 개발 환경과 Kakao Cloud deployment가 있으며, air-gapped install profile도 별도로 운영합니다.

상세 기술 문서

주제문서내용
Overview플랫폼 개요IDP 범위와 integration-first 철학
Architecture아키텍처HA control plane, network, service layout
GitOpsGitOpsArgo CD + Gitea App-of-Apps
Networking네트워킹Cilium, MetalLB, APISIX, DNS
Security보안/SSOKeycloak, OpenBao, Kyverno, TLS
Observability관측성Prometheus, Grafana, Loki, Tempo, Hubble
Storage스토리지NFS CSI, SeaweedFS, quota, PostgreSQL
Operations운영backup, restore, upgrade, air-gap
Testing검증/카오스regression, cluster verification, chaos

프로젝트 관계

Architecture diagram
Responsive vector rendering · source preserved
kube-ready-box ↓ Narwhal IDP nfs-quota-agent ldapium Narwhal Portal OpenForge shared engineering / supply-chain practices