아키텍처와 개념

📚 문서 홈 — 본 문서는 시스템 아키텍처 개요입니다. 화면 사용법은 사용자 가이드 및 관리자 가이드를 참고하세요.

시스템 개요

gShare는 GPU 자원을 직접 분할하지 않습니다. 실제 GPU 분할은 HAMi를 통해 VRAM 및 GPU 코어 한도를 할당받거나, 단일 카드 전체를 전용으로 할당합니다. gShare는 그 상위에서 작동하는 **제어 플레인(Control Plane)**으로, 자원 할당 주체, 사용 목적, 실행 시간, 과금 체계 등을 통합 관리합니다. 일반적인 Kubernetes + HAMi 환경에 세션 승인, 점유율 기반 과금, 계층적 자원 정책 한도, 유휴 자원 자동 회수 메커니즘을 결합하여 다중 조직·부서·사용자가 단일 클러스터 자원을 효율적으로 공유할 수 있도록 지원합니다.

구성 요소 및 아키텍처 흐름

  사용자와 관리자
      │  브라우저
      ▼
  콘솔 (frontend, React SPA)             ── 사용자·관리자 화면, REST + SSE
      │  REST / SSE
      ▼
  제어 플레인 (backend, Python/FastAPI)   ── 상태와 돈의 주인: 인증, 인가, 크레딧,
      │   ├ gshare-api    : 승인, CRUD, 토큰 발급           예산, 카탈로그, 정책, 스케줄링
      │   └ gshare-worker : 과금, 예산 집계, 대기열, 리필
      │  GShareSession CR 적용 (kubeconfig 경유)   ▲ 서명된 상태·인벤토리 콜백
      ▼                                          │ (내부 JWT)
  오퍼레이터 (Go, 클러스터당 하나) ──▶ Pod / Service / Ingress / Secret (gshare-sessions)
      │                                  세션 파드 = 인터랙티브 환경
      ▼                                  (VS Code, JupyterLab, 웹 터미널)
  HAMi + GPU 노드                     ── 실제 분할(gpumem / gpucores) 또는 카드 전체

  postgres (상태와 원장) · redis (대기열, 토큰, 락)

구성 요소	기술 스택 / 위치	주요 역할 및 기능	세부 설명 문서
콘솔	React + TypeScript · `frontend/`	REST API 및 SSE 기반의 사용자 및 관리자 웹 SPA 서비스	frontend/README
제어 플레인	Python + FastAPI · `backend/`	사용자 인증/인가, 세션 CRUD, 토큰 발급, 크레딧 과금 및 정산, 스케줄링 승인	backend/README
오퍼레이터	Go · `operator/`	`GShareSession` 커스텀 리소스를 감지하여 파드, 서비스, 인그레스 생성 및 상태 보고	operator/README
GPU 분할	HAMi (외부 솔루션)	VRAM 및 GPU 코어 단위 vGPU 분할 또는 물리 카드 전용 할당 처리	—

제어 플레인은 특정 클러스터 환경에 종속되지 않는 독립적 구조를 가집니다. 외부 GPU 클러스터에 kubeconfig를 통해 커스텀 리소스(CR)를 배포하며, 각 클러스터에 상주하는 오퍼레이터가 이를 감지·재조정한 후 서명된 내부 JWT 콜백을 통해 자원 상태 및 인벤토리를 제어 플레인으로 동기화합니다. 자원 할당 및 크레딧 과금에 대한 모든 권한과 결정은 제어 플레인에서 관리됩니다.

핵심 개념

오퍼링 (Offering): GPU 모델 카탈로그 정보입니다. 물리 카드 전체 스펙을 기준으로 단일 항목이 구성되며 시간당 크레딧 단가를 정의합니다. 세션 생성 시 선택 항목으로 활용됩니다.
프리셋 (Preset): 세션 스펙 카탈로그입니다. 컴퓨트 자원(CPU, 메모리, 임시 디스크) 및 GPU 분할 티어(XL ½, L ¼, M ⅛, S 1/16) 또는 전용 카드 할당 옵션을 정의합니다. VRAM 및 코어 한도는 오퍼링의 전체 카드 스펙에 티어 비율을 적용하여 자동 계산됩니다.
세션 (Session): 파드 기반의 인터랙티브 작업 환경입니다. 자원 사용 모드는 공유(Fractional) 또는 **전용(Exclusive)**으로 구분됩니다. (MIG는 세션 모드가 아닌 노드 카드 단위 풀이며, 자원 프로파일이 부합하는 공유 요청은 MIG 인스턴스에 투명하게 배치됩니다.)
점유율 (Ratio): max(VRAM 비율, 코어 비율) 공식으로 산출됩니다. 과금은 단가 × 점유율 × 실행 시간으로 계산되며, 전용 세션의 점유율은 1.0으로 고정됩니다.
크레딧, 지갑 및 예산: 크레딧은 계층 구조(시스템 → 조직 → 부서 → 개인)를 따라 차례로 배분되지만, 실제 세션 과금은 요청자 본인의 개인 지갑에서만 차감됩니다. 예산은 범위별 자원 한도 게이트로 동작하며 경고 또는 실행 차단 정책을 적용할 수 있습니다.
자원 정책 (Resource Policy): 동시 세션 수, 총 할당 자원 한도, 유휴 시간제한 등을 관리합니다. 적용 우선순위는 가장 구체적인 정책 범위부터 적용됩니다 (사용자 → 부서 → 조직 → 전역).
일시정지 및 재개 (Pause & Resume): 세션 일시정지 시 파드가 종료되며 오퍼레이터가 GPU 자원을 즉시 반납하고(타 세션 할당 가능) 과금을 중단합니다. 세션 설정 및 마운트된 영구 볼륨은 유지되며(무료 제공), 세션 재개 시 GPU 자원을 재확보하여 파드를 재생성합니다. 유휴 GPU 세션은 시스템 정책에 따라 자동으로 일시정지되어 효율적인 자원 회수를 지원합니다.
대기열 및 우선순위 (Queue & Priority): 클러스터 가용 자원이 부족한 경우 세션 생성이 즉시 실패하지 않고 대기열에 진입하며, 자원 확보 시 우선순위에 따라 순차 승인되어 실행됩니다.
볼륨 (Volume): 읽기 전용 또는 읽기/쓰기 모드를 지원하는 영구 개인 및 부서 공유 스토리지입니다. 크레딧 과금이 발생하지 않으며, 자원 정책의 계정별·부서별 스토리지 쿼터로 사용량이 제한됩니다.
RBAC (Role-Based Access Control): 권한 범위에 따라 super_admin(전체), org_admin(조직 단위), group_admin(부서 단위), member / guest(일반 사용자) 역할로 구분되며, 일반 콘솔과 관리자 콘솔 인터페이스가 분리되어 제공됩니다.
CUDA 호환성: 선택한 이미지의 CUDA 버전이 오퍼링에 지정된 min_cuda 최소 요구 기준보다 낮은 경우 세션 생성이 거부됩니다.

세션 승인 워크플로우

세션 생성 요청 시 인프라 자원이 할당되기 전 다음 검증 단계를 순차적으로 수행합니다.

참조 및 CUDA 검증: 오퍼링, 이미지, 개인 지갑의 유효성을 검증하고, 이미지의 CUDA 버전이 오퍼링 최소 요구조건을 충족하는지 확인합니다.
마운트 권한 검증: 요청한 볼륨에 대해 지정한 접근 모드로 마운트 가능한 권한이 있는지 확인합니다.
과금 지갑 검증: 과금 대상 지갑이 요청자 본인의 개인 지갑인지 확인합니다.
자원 정책 한도 검증: 동시 실행 세션 수 및 총 자원 쿼터 한도를 단계별로 검증합니다 (사용자 → 부서 → 조직 → 전역).
예산 게이트 검증: 해당 범위의 예산 상태를 검증하며, 차단형 예산 초과 시 요청이 거부됩니다.
크레딧 선예약: 예상 실행 비용을 개인 가용 잔액에서 선예약합니다 (잔액 부족 시 거부).
VRAM 및 GPU 배치 예약: 자원 점유율을 고려한 2차원 Best-fit 알고리즘으로 적합한 GPU 카드를 선택합니다 (가용 자원 부족 시 대기열 진입).
오퍼레이터 인계 및 실행: 커스텀 리소스(CR) 적용, 파드 생성, Running 상태 콜백 수신 후 과금이 시작됩니다.

Note: CPU 전용 세션은 무료로 제공되며 예산, 선예약, VRAM 배치, 대기열, GPU 과금 검증 단계를 건너뜁니다.

차별화된 핵심 기능

gShare는 기본 분할 메커니즘(HAMi) 상위에서 자원 점유율 기반 스케줄링 배치 및 과금 관리, 세션 일시정지를 통한 유휴 GPU 자원 자동 회수, 선점 및 제자리 GPU yielding(무손실 상태 이관 및 재개), 다단계 계층적 쿼터 한도 제어를 통합하여 제공합니다.

네임스페이스 구성

네임스페이스	설명 및 용도
`gshare-system`	제어 플레인 구성 요소 (API, Worker, Operator, Postgres, Redis, Ingress)
`gshare-sessions`	사용자 테넌트 세션 파드 배치 영역 (Pod Security Admission은 `baseline` 정책을 강제하며 `restricted` 수준은 Audit/Warn 적용)
`gshare-infra`	특권 DaemonSet 구성 요소 (node-problem-detector, Spegel, 이미지 프리풀러 등)

노드별 실시간 지표 에이전트 (선택 사항)

gshare-agent는 각 세션 파드의 cgroup v2 카운터(cpu.stat, memory.current)를 노드에서 1초 간격으로 직접 수집하여 내부 JWT 인증을 통해 제어 플레인으로 전송하는 DaemonSet입니다. 수집된 메트릭 샘플은 세션당 5분 분량의 링 버퍼(Ring Buffer) 형태로 Redis에 저장되며 GET /sessions/{id}/usage/live API를 통해 조회됩니다. 에이전트 활성화 시 세션 상세 페이지에서 CPU 및 메모리 사용량을 1초 실시간 그래프로 표시하며, 미활성화 시 Prometheus 시계열 데이터로 대체 표시됩니다.

cAdvisor의 기본 하우스키핑 집계 주기(약 10초)로 인한 모니터링 지연을 최소화하기 위해 해당 에이전트를 제공합니다. 에이전트 적용 시 약 1초 이내에 실시간 사용량 변화를 모니터링 화면에 반영할 수 있습니다.

에이전트는 기본적으로 비활성화되어 있으며 gshare-infra 네임스페이스에서 실행됩니다 (읽기 전용 /sys/fs/cgroup hostPath 바인딩 필요). 특권 권한 없이 노드 내 파드 지표만 수집하며, 시스템 핵심 동작은 에이전트 존재 여부에 영향을 받지 않습니다. 전체 시스템의 영구 시계열 데이터 및 종합 이력은 Prometheus에서 계속 관제 및 보관합니다.

시스템 개요​

구성 요소 및 아키텍처 흐름​

핵심 개념​

세션 승인 워크플로우​

차별화된 핵심 기능​

네임스페이스 구성​

노드별 실시간 지표 에이전트 (선택 사항)​