WORK / ACTIVE SYSTEM

Beluga

로컬 Kubernetes에서 Kafka·CDC·Flink·Iceberg·Trino·Superset·Airflow를 통합하는 데이터 플랫폼. 통합 control plane(manager/)을 같은 저장소에 포함

Kubernetes · k3s · Data Platform · Kafka · Debezium · Flink · Iceberg · Trino · Airflow · GitOps · Control Plane
01 / Problem02 / Architecture03 / Development04 / Proof05 / Knowledge06 / Record
01 / PROBLEM

모던 데이터 플랫폼의 핵심 컴포넌트는 각각 쉽게 설치할 수 있지만 CDC, streaming, lakehouse, query, BI, orchestration의 경계를 로컬 환경에서 일관되게 연결하고 검증하기가 어려움

RESPONSE

Vagrant와 k3s 위에 Helm·Argo CD GitOps로 전체 데이터 플랫폼을 재현하고, synthetic clickstream과 PostgreSQL CDC 두 가지 end-to-end 시나리오로 실제 동작을 검증

02 / ARCHITECTURE

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

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

Beluga data flow from Kafka and Debezium through Flink, Iceberg, Lakekeeper, Trino, Superset and Airflow
Beluga data platform flow from CDC and streaming to lakehouse, SQL, BI and orchestration.
ARCHITECTURE / HOW IT WORKS

Beluga Data Platform Pipeline

01
Kafka + Debezium
Events · CDC
02
Flink
Stream processing
03
Iceberg + Lakekeeper
Lakehouse · REST catalog
04
Trino + Superset
Distributed SQL · BI
05
Airflow
Orchestration
A GitOps-deployed data platform from streaming and CDC ingestion through stream processing and Iceberg storage to query, BI, and orchestration.
DATA FLOW / VISUAL EVIDENCE

Streaming to lakehouse to analytics

01
Kafka + Debezium
02
Flink processing
03
Iceberg + Lakekeeper
04
Trino + Superset + Airflow
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/beluga

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

Contributors: 3
첫 commit
2026년 8월 9일
누적 commits
961
Releases
2
최신 release
v0.2.0
최근 push
2026년 11월 22일
개발 기간
3개월
최근 개발 활동
797 commits / 20 weeks
PAST → NOW
언어: TypeScript라이선스: Apache-2.0Stars: 0Forks: 0Open issues: 118최신 release
04 / PROOF, NOT BADGES
11
technology / domain signals

Declared scope and technical context

6
connected docs

Operational or implementation documentation

1
engineering notes

Knowledge produced by the project

0
digest links

External signals explicitly connected

06 / ENGINEERING RECORD

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

프로젝트 소개

Beluga는 개인 개발 환경에서 현대적인 데이터 플랫폼의 전체 흐름을 재현하기 위한 Kubernetes 기반 self-hosted data platform입니다.

핵심은 개별 OSS를 모아 놓는 것이 아니라 다음과 같은 데이터 lifecycle을 하나의 재현 가능한 환경에서 검증하는 것입니다.

Beluga는 “프로덕션 규모 데이터 플랫폼”을 표방하지 않습니다. 로컬에서 데이터 플랫폼의 통합 동작, 권한 모델, storage/query 경계와 GitOps 운영 패턴을 실험하기 위한 개인/학습 스케일 reference platform입니다.

플랫폼 구성

영역컴포넌트역할
Clusterk3s + Cilium + MetalLB로컬 Kubernetes 실행 기반
GatewayAPISIX + etcd플랫폼 UI 및 API entrypoint
GitOpsArgo CDapp-of-apps 기반 선언적 배포
IdentityKeycloak + OpenLDAP인증 및 그룹 기반 접근 제어
PolicyOPA + OpenFGA서비스 정책과 lakehouse 인가
StreamingStrimzi Kafka + DebeziumEvent streaming / CDC
ProcessingFlink Kubernetes OperatorStatefull stream processing
CatalogLakekeeperIceberg REST catalog
StorageSeaweedFSS3-compatible object storage
DatabaseCloudNativePGPostgreSQL source / metadata DB
QueryTrinoIceberg distributed SQL
BISupersetInteractive analytics / dashboards
OrchestrationAirflow 3compaction / aggregation DAG
Optional GovernanceOpenMetadata + OpenSearchmetadata / lineage
ObservabilityPrometheus Stackplatform metrics

정확한 버전/이미지/라이선스의 단일 원천은 저장소의 VERSIONS.md이다. 주요 핀 예시: Kubernetes v1.36(k3s 채널), Strimzi Kafka Operator 1.1.0(KRaft, Kafka 4.3.0), Debezium 3.6.1.Final, Flink Kubernetes Operator 1.15.0(런타임 Flink 1.20.0), Lakekeeper v0.13.1, Trino 483, Airflow 3.3.0, Superset 6.1.0, Keycloak 26.7.1, CloudNativePG(PostgreSQL 17.6).

핵심 설계 포인트

1. Kubernetes가 데이터 플랫폼의 공통 운영 경계

각 데이터 컴포넌트가 서로 다른 설치 방법을 사용하지 않도록 Helm과 Operator를 중심으로 Kubernetes 리소스에 맞춥니다. Beluga의 주요 차트는 beluga-platform과 beluga-data로 계층화되어 있습니다.

2. GitOps가 실제 deployment contract

Argo CD App-of-Apps를 통해 플랫폼과 데이터 레이어를 선언적으로 배포합니다. 따라서 “로컬에서 한 번 잘 동작했다”가 아니라 Git 상태와 실제 cluster 상태를 비교할 수 있습니다.

3. 데이터 경로를 두 개의 시나리오로 검증

  • Clickstream demo — synthetic events → Kafka → Flink → Iceberg → Trino/Superset
  • PostgreSQL CDC — PostgreSQL → Debezium → Kafka → Flink → Iceberg

이는 단순 chart install 성공보다 실제 데이터가 경계를 통과하는지를 검증합니다.

아키텍처

로컬 리소스 모델

Beluga는 VM 4대와 전체 데이터 스택을 함께 구동하므로 가벼운 demo가 아닙니다.

  • 최소 호스트 RAM: 32GB
  • 48GB 이상: OpenMetadata 및 Trino worker 등 확장 profile 사용 가능
  • 64GB 이상: worker memory 추가 확장
  • VMware Fusion(ARM64) 또는 VirtualBox(AMD64) 지원
  • 실제 메모리 상황에 따라 profile을 자동 선택

따라서 Kube-Ready-Box처럼 “노드 baseline”을 제공하는 프로젝트와 달리 Beluga는 전체 data platform 통합 비용을 한 번에 보여주는 상위 reference environment입니다.

검증 구조

Beluga는 렌더링 성공과 실제 동작을 구분합니다.

각 단계는 “서비스가 설치되었는가”가 아니라 실제 API와 데이터 흐름이 기대한 상태인지 확인합니다.

보안 및 자격증명

Beluga는 repository에 비밀번호를 커밋하지 않고 bootstrap 시점에 credential을 생성합니다. Kubernetes Secret에 저장하고 Helm에는 값 자체가 아니라 필요한 참조만 넘기는 구조를 사용합니다.

또한 policies/를 별도 source of truth로 두어 Keycloak, Rego, PostgreSQL 권한 산출물 사이의 일관성을 관리하려는 방향을 취합니다.

Operations Agent (읽기 전용 PoC)

이슈 #108의 첫 안전 실행 슬라이스로, scripts/agent/operations_agent.py가 클러스터를 관찰하고 장애 신호를 수집해 mutation 없이 remediation 제안만 만드는 read-only PoC입니다.

  • 실행 경로는 OpenForge Agent Execution Security 원칙을 따릅니다: 요청 → 고정 tool/target 해석 → canonical invocation digest → risk 분류 → 요청측 인가 → 고정 argv executor(읽기 전용만) → 결과 해싱/findings → evidence 기록.
  • configs/operations-agent-policy.json이 tool별 risk class를 선언합니다 — cluster.nodes/cluster.pods/cluster.events/gitops.applications는 read-only-diagnostic으로 실행 가능하고, data.mutate/external.http/platform.privileged는 approvalRequired: true이면서 PoC 단계에서는 executable: false로 원천 차단됩니다. approval 플래그가 비활성 class를 실행 가능하게 만들지는 않습니다.
  • 안전 불변식: model이 생성한 자유 형식 shell/kubectl 인자를 실행하지 않고 code-owned argv만 subprocess에 도달, 공유 ~/.kube/config 대신 격리된 kubeconfig 강제, Kubernetes context는 항상 beluga, evidence에는 원본 출력 대신 해시/바이트 수/상태만 저장.
  • cluster-inspector·data-service-inspector·identity-inspector·storage-inspector·observability-inspector·hypothesis-agent·verifier로 역할이 설계되어 있으나, 현재 구현은 공용 read-only 검사 경계뿐이고 role별 그래프 오케스트레이션은 아직 future work입니다.
  • make test-agent로 라이브 클러스터 없이 정책/보안 스위트를 검증하며, 이 계약을 지키는 CI(operations-agent-security.yml)가 상시 구동됩니다.

현재 상태

Beluga는 개인/학습 스케일의 reference implementation입니다.

  • 핵심 Kafka/CDC → Flink → Iceberg → Trino/Superset/Airflow 흐름은 clean-install E2E를 목표로 구현되었고 완료로 표시됨(docs/IMPLEMENTATION-STATUS.md, 2026-09-14 검증)
  • 라이브 클러스터가 항상 실행 중인 것은 아니므로(vagrant status 기준 VM 4대 모두 중지) 모든 최신 변경이 상시 live validation되는 것은 아님
  • 정책 컴파일러는 manager/로 통합되어 같은 트리에서 실행되며, 거버넌스 영역은 계속 진화
  • Operations Agent는 read-only 진단 프로파일만 실행 가능하며, data mutation/외부 egress/privileged 작업 실행은 계약상 비활성화된 상태
  • 2026-08-28 이후에도 MetalLB L2Advertisement를 사설 네트워크 인터페이스로 제한, ArgoCD·OpenMetadata UI를 APISIX 뒤에서 언블록, 인증서 key usage 명시, VMware Fusion 프로바이더를 vagrant-vmware-desktop(vmware_desktop)으로 교체, 64GB 호스트용 VM RAM 프로파일 튜닝 등 클러스터 안정화 커밋이 계속 들어가고 있음

Beluga Manager (manager/)

Beluga Manager는 Beluga 데이터 플랫폼의 통합 Control Plane입니다. 별도 저장소 dasomel/beluga-manager였으나 2026-10-15 ADR-0005에 따라 이 저장소의 manager/ 디렉터리로 통합(전체 히스토리 보존)되었고, 이전 저장소는 아카이브되었습니다.

Kafka, Flink, Iceberg, Trino, Airflow는 계속 자신의 리소스에 대한 authoritative system이고, Manager는 OSS UI를 복제하지 않고 이들의 API를 adapter로 연결해 플랫폼 수준의 질문(어떤 Topic이 어떤 Job과 Table로 이어지는가, 어느 서비스가 degraded인가)에 답합니다.

도메인역할
PipelineKafka → Flink → Iceberg → Trino 데이터 흐름의 cross-service 상관
Data Assetcatalog, schema, table과 query context
Service개별 OSS를 platform capability로 표현 (identity, version, health, dependency)
Operationshealth, event, resource, dependency를 하나의 context로 묶음

저장소 구성 — manager/는 자체 package.json과 lockfile을 가진 npm workspace(packages/domain-api, packages/policy-compiler, packages/web)이고, .github/workflows/manager-ci.yml이 manager/** 변경에만 CI를 실행합니다. 릴리스는 플랫폼과 독립적입니다.

Policy compiler seam — policies/의 YAML은 manager/packages/policy-compiler가 Keycloak, Trino OPA Rego(trino.rego), PostgreSQL DDL(db-roles.sql)로 컴파일합니다. 통합 전에는 두 워크플로가 서로 다른 SHA로 고정한 외부 체크아웃을 썼지만, 지금은 테스트 14와 ci.yml/release.yml이 같은 트리의 manager/에서 컴파일러를 실행합니다. 컴파일러 변경과 재생성된 산출물은 한 PR로 들어갑니다.

현재 성숙도 (2026-10-15 확인) — Domain API와 웹 콘솔(Overview·Services·Pipelines·Data Catalog·Query Workspace·Policy 등)과 policy compiler는 구현·테스트되어 있습니다. 다만 Domain API는 기본적으로 저장소 내 fixture(stub)로 응답하고, opt-in 읽기 전용 어댑터는 Flink·Trino 쿼리 이력·Lakekeeper 3종뿐이며 live 클러스터 검증이 기록된 것은 Flink 어댑터입니다. Kafka·Debezium·Airflow 어댑터, 인증/인가 미들웨어와 클러스터 배포 차트는 없습니다. upstream 호스트는 *.local.beluga.internal에 고정되어 있습니다. 완성된 운영 콘솔이 아니라 read-first 단계입니다.

열려 있던 beluga-manager 이슈 22건은 이 저장소의 #239–#260(area:manager 라벨)으로 이전되었습니다. 자세한 내용은 매니저 개요, 아키텍처, 개발, 운영을 참고하세요. 통합 배경은 블로그 글 beluga-manager를 beluga 모노레포로 통합한 이유에 정리했습니다.

시작하기

git clone https://github.com/dasomel/beluga.git
cd beluga
make up
make status
make test

상세 기술 문서

주제문서내용
Overview플랫폼 개요문제 정의와 제품 범위
Architecture아키텍처전체 데이터 흐름과 컴포넌트 경계
Getting Started설치 가이드VM → k3s → GitOps bootstrap
Operations운영 가이드상태, upgrade, data lifecycle
Troubleshooting문제 해결cluster, Kafka, Flink, query 장애
Manager매니저 개요manager/ control plane 범위와 현재 구현 상태
Manager Architecture컨트롤 플레인 아키텍처Adapter, correlation, policy seam
Manager Development개발 가이드cd manager && npm install
Manager Operations배포 및 운영현재 배포 경계

프로젝트 관계