OpenForge 문서 목차 보기
ClusterDeck · OSS Project

ClusterDeck

변하는 VM·Kubernetes 환경을 Profile 중심으로 발견하고 SSH·kubeconfig 연결을 자동화하는 macOS 데스크톱 도구

macOSTauriRustReactTypeScriptSSHKuberneteskubeconfigProxyJump
RepositoryGitHub ↗
Documentation3 sections
Updated2026-10-27T00:00:00.000Z
ECOSYSTEM ROLE
Workstation Access Layer

자주 재생성되는 VM·Kubernetes 환경을 IP가 아닌 안정적인 Profile로 다루고 SSH, Bastion/ProxyJump, kubeconfig 연결을 로컬 워크스테이션에서 자동화합니다.

Profile-oriented accessSSH & ProxyJumpkubeconfig normalization
PROJECT CONFORMANCE

저장소 evidence 체크리스트

3 present · 6 missing

Present는 저장소 또는 사이트에서 명시적 artifact가 관찰됐다는 뜻입니다. Missing은 audit에서 해당 artifact를 찾지 못했다는 뜻이며 실제 practice가 없다는 증거는 아닙니다. Tracked는 가장 가까운 기존 backlog owner를 가리키며 이슈를 자동 생성하지 않습니다.

CONTRIBUTING
Missing
CODE_OF_CONDUCT
Missing
SECURITY.md
Missing
SBOM evidence
Missing
Provenance / attestation
Missing
GitHub Release
Present
Evidence 확인됨
프로젝트 상세 Docs
Present
3 sections
Evidence 확인됨
Community contributor 신호
Present
3 contributors
Evidence 확인됨
repository audit 미인덱싱
Problem

로컬 VM과 Kubernetes 실습·개발 환경을 자주 생성·삭제하면 IP가 바뀌고 SSH alias, Bastion/ProxyJump, 원격 kubeconfig, context 이름을 매번 수동으로 다시 연결해야 함

Approach

사용자가 IP 대신 안정적인 Profile 이름을 유지하도록 하고 host discovery → SSH bootstrap → alias/ProxyJump → kubeconfig fetch/normalize → Kubernetes connectivity check 흐름을 하나의 macOS 데스크톱 UX로 묶음

ENGINEERING EVIDENCE

숫자보다 검증 가능한 근거를 보여줍니다.

User model
Profile-first

Keeps a stable environment identity while VM or cluster IP addresses change.

Access path
SSH + Bastion

Orchestrates connectivity, public-key bootstrap, aliases, and ProxyJump with native OpenSSH behavior.

Kubernetes
kubeconfig sync

Fetches remote kubeconfig, normalizes endpoint/context names, and stores per-Profile local configuration.

Verification
3 layers

Separates SSH, kubeconfig, and Kubernetes API connectivity so failures are visible at the correct boundary.

START HERE

README를 처음부터 읽지 않아도 됩니다.

ENGINEERING PRINCIPLES
Source-driven

설명은 repository의 source, architecture, tests, release와 운영 기록을 근거로 유지합니다.

Independently useful

생태계에 속하더라도 가능한 한 독립 설치·검증·릴리스 가능한 경계를 유지합니다.

Evidence over claims

기능 개수보다 재현 가능한 검증, 장애 지식, upgrade gate와 운영 증거를 우선합니다.

프로젝트 소개

ClusterDeck은 자주 재생성되는 VM 및 Kubernetes 환경에 대한 로컬 접속 경로를 안정적으로 유지하기 위한 macOS 중심 데스크톱 도구입니다.

일반적인 Kubernetes 관리자 콘솔이 아니라, 원격 환경을 발견하고 접속 가능한 상태로 만드는 workstation access layer에 집중합니다. 사용자는 매번 달라지는 IP를 기억하는 대신 Profile 이름을 유지하고, ClusterDeck이 SSH와 kubeconfig 경계를 정리합니다.

IP / Host Discovery
      ↓
SSH Connectivity
      ↓
SSH Bootstrap (optional)
      ↓
SSH Alias / ProxyJump
      ↓
Remote kubeconfig Fetch
      ↓
kubeconfig Normalization
      ↓
Local Profile
      ↓
Kubernetes Connectivity Check

핵심 설계

  • Tauri 2 + Rust: SSH orchestration, filesystem, process execution, kubeconfig 처리 등 로컬 시스템 작업의 보안 경계를 backend에 둡니다.
  • React + TypeScript: Profile, Host, Connect, Status 중심의 간결한 데스크톱 UI를 제공합니다.
  • Native OpenSSH 우선: 자체 SSH stack을 다시 구현하지 않고 ssh, scp, ssh-copy-id, ProxyJump 같은 검증된 동작을 활용합니다.
  • Profile 중심 모델: IP 주소보다 사람에게 안정적인 environment identity를 유지합니다.
  • ClusterDeck-owned config: 사용자 전체 ~/.ssh/config를 덮어쓰지 않고 ~/.clusterdeck/ 아래의 생성 파일만 소유합니다.

보안 경계

초기 비밀번호는 bootstrap용으로만 사용하고 저장하거나 로그에 남기지 않는 것을 원칙으로 합니다. 생성 kubeconfig는 제한된 파일 권한을 사용하고, 사용자 관리 SSH/Kubernetes 설정을 파괴적으로 덮어쓰지 않습니다.

ClusterDeck이 ~/.clusterdeck/ 바깥에서 실제로 건드리는 것은 네 가지뿐이며, 전부 opt-in이거나 자기 소유 블록만 씁니다.

  • 로그인 키체인 — 클러스터 내부 CA를 신뢰하도록 선택하면(엔드포인트별 opt-in, 또는 Settings → Trusted CAs) System이 아닌 로그인 키체인에 SSL/TLS 신뢰 정책 범위로만 추가합니다. Keychain Access.app에서 확인하거나 ClusterDeck에서 직접 해지할 수 있습니다.
  • /etc/hosts — 기본 off, Profile별 opt-in. 켜면 # >>> ClusterDeck BEGIN (profile: <id>) >>> 마커로 감싼 자기 블록만 admin 권한 프롬프트로 씁니다.
  • 로컬 DNS (v0.5.0, Profile별 opt-in) — host_mapping: local_dns를 켜면 # managed by ClusterDeck (profile: <id>) 마커가 붙은 /etc/resolver/<zone> 파일만 admin 권한 프롬프트로 쓰고, 사용자 LaunchAgent com.clusterdeck.dns가 127.0.0.1:15353에서 loopback 전용 DNS 응답기를 실행합니다. Safari·URLSession이 /etc/hosts를 무시하는 환경을 위한 경로입니다.
  • ~/.ssh/config — Include ~/.clusterdeck/ssh/*.conf 한 줄만 추가하고, 실제 per-profile SSH 옵션은 그 include 디렉터리 안에 둡니다.

다운로드

최신 릴리스 v0.5.0(2026-10-26)이 macOS Apple Silicon(aarch64)과 Intel(x64) .dmg로 배포됩니다(CHANGELOG 기준 Intel 빌드는 Apple Silicon CI 러너에서 빌드되었고 Intel 하드웨어에서는 아직 실행 검증되지 않음). 서명되지 않은 ad-hoc 빌드이며 Apple Developer ID 서명이 아직 없어 최초 실행 시 "확인되지 않은 개발자" 경고가 뜨므로, 앱을 우클릭 후 열기로 실행해야 합니다.

v0.5.0은 내장 로컬 DNS, bastion 뒤 클러스터 API용 앱 관리 SSH 터널, 로컬 VM 인벤토리(Colima·VirtualBox·VMware Fusion·Vagrant)와 Demo 모드(InfraDeck 흡수)를 추가했습니다.

MVP 범위

  1. Profile CRUD
  2. Multi-host discovery와 SSH bootstrap
  3. SSH alias 생성
  4. Bastion / ProxyJump
  5. Remote kubeconfig fetch 및 normalization
  6. Profile별 kubeconfig 저장
  7. Kubernetes connectivity verification
  8. 최소 클릭 중심 macOS UI

Cross-platform 지원과 provider-specific discovery는 core workflow 안정화 이후 범위입니다.

개발

pnpm install
pnpm tauri dev
 
pnpm build
cargo check --manifest-path src-tauri/Cargo.toml

소스 실행이 여전히 권장 경로이며, .dmg 배포는 개발용 실행을 대체하지 않는 보조 경로입니다.

상세 문서

주제문서내용
Overview개요문제 정의, 범위, Profile 중심 모델
Architecture아키텍처Tauri/Rust, SSH, kubeconfig 경계
Getting Started시작하기개발 환경과 기본 연결 흐름

프로젝트 관계

Local VM / Kubernetes labs
        ↓
    ClusterDeck
        ↓
SSH / Bastion / kubeconfig access
        ↓
Narwhal · Beluga · test clusters