이 페이지는 요약입니다. 설치·환경변수·권한·운영 절차의 정본은 저장소의 관리자 가이드(Markdown)와 PDF입니다. 내용이 다르면 정본을 따르세요.
관리자 시작 순서
- Bootstrap 계정 보호
최초 로그인 후 로컬 비밀번호를 변경하고 접근 경로를 제한합니다. - 데이터·키 정책
원시 메트릭 보존일, 사용량 집계 보존일, 개인 키 회전·최대 수명과 역할별 권한을 정합니다. 서비스명과 한국어 UI는 현재 릴리스에서 고정입니다. - Keycloak SSO
연결 테스트를 통과한 뒤 저장하고 실제 OIDC 로그인을 확인합니다. - JupyterHub 등록
망별 Hub 등록 Drawer에서 현재 입력값을 진단한 뒤 저장하고 최초 동기화 결과를 확인합니다. - 선택 Provider
필요한 Prometheus·Kubernetes·AI·Webhook만 연결합니다. - 기능·Workflow
선택형 GPU·LLM과 서버 동작 승인 Workflow를 필요한 경우에만 켭니다.
서비스 관리에는 기본 설정, 연동, 기능 Switch, 승인 Workflow, 키 정책과 역할 관리가 있고, 정책·Profile·Image·프로젝트·Incident 등은 별도 CRUD 메뉴로 관리합니다. 개인화에는 내 프로필, 로컬 비밀번호와 개인 API 키가 있습니다. 메뉴 노출과 route 접근은 backend permission으로 제한됩니다.
모든 연동의 표준 절차
- 설정 입력
화면에 제공되는 URL, 식별자와 credential을 입력합니다. secret은 저장 후 마스킹되고 다시 노출되지 않습니다. - 저장 전 “연결 테스트”
현재 폼값을 저장하지 않은 상태에서 URL 형식, 시스템 신뢰 저장소 기반 TLS와 연동별 HTTP 호출을 검사합니다. - 단계 결과 확인
각 요청의 성공/실패·HTTP 상태·소요시간, 전체 응답시간과 실패 원인·조치 안내를 확인합니다. - 저장
결과를 확인한 뒤 별도로 저장합니다. 테스트 성공이 자동 저장을 의미하지 않습니다. - 실제 흐름 검증
OIDC code·token·claim 검증과 AI SSE streaming처럼 시험 endpoint가 대신할 수 없는 동작은 저장 후 확인합니다.
| 공통 표시 | 현재 버전 범위 |
|---|---|
| URL | http(s) 형식과 안전한 endpoint 조합 |
| TLS | 설정된 검증 Switch와 시스템 CA 신뢰 저장소 사용 여부 |
| 단계 | 연동별 실제 HTTP API 성공 여부와 상태 |
| 버전 | JupyterHub와 Kubernetes처럼 응답에 버전이 있는 연동 |
| 응답시간 | 단계별·전체 소요시간 |
| 실패 안내 | 망·URL·권한·인증·TLS 확인 방향 |
인증서 만료일, 사용자 CA 업로드, DNS/connect/TLS/first-byte 구간별 timing과 모든 원격 권한을 공통으로 검사하는 기능은 현재 버전에 없습니다. 아래 연동별 실제 호출 범위를 기준으로 판정하세요.
연동별 설정과 검사
Keycloak OIDC
| 입력 | Issuer URL, Client ID·Secret, Redirect URL, Scopes, username claim, 자동 사용자 생성, TLS 검증 |
|---|---|
| 연결 테스트 | Discovery 조회 → authorization/token/JWKS endpoint 존재 → Client ID 입력 여부 → 응답시간 |
| 저장 후 | 별도 브라우저에서 authorization code·PKCE·ID token·issuer/audience/nonce와 username/name/email/department claim을 실제 검증 |
JupyterHub
| 입력 위치 | JupyterHub 관리 → Hub 등록·수정 Drawer |
|---|---|
| 입력 | Hub 이름, 망, Base URL, Admin API Token, TLS 검증, Hub별 수집 주기, 중앙 관리 여부 |
| 저장 전 연결 테스트 | 현재 Drawer의 URL·TLS·token으로 /hub/api/info 버전 → /hub/api/users?limit=1 관리자 조회 권한 → 응답시간을 확인합니다. 편집 중 URL·TLS가 저장값과 같을 때만 비어 있는 token 대신 해당 Hub의 암호화 token을 사용합니다. URL·TLS가 바뀌면 token을 다시 입력해야 하며 테스트 자체는 설정을 변경하지 않습니다. |
| 저장 후 | Hub 목록에서 상태를 확인하고 지금 동기화를 실행해 사용자·서버를 확인합니다. 서버 제어는 별도 시험 계정으로 검증합니다. |
중앙 관리 OFF의 범위: 해당 Hub collector를 중지하고 이전 running snapshot을 현재 대시보드 KPI·실시간 세션·Hub 카드 수치에서 제외합니다. 이미 기록된 기간별 Usage·LLM 사용량과 감사 이력은 과거 사실이므로 삭제하거나 숨기지 않습니다.
Prometheus
| 입력 | Base URL, Bearer Token, TLS 검증 |
|---|---|
| 연결 테스트 | /api/v1/query?query=vector(1) 조회 성공과 응답시간 |
| 수집 | 기본 CPU core·메모리 byte query와 선택형 GPU Util·VRAM query를 주기적으로 실행 |
Kubernetes
| 입력 | API Server URL, namespace, ServiceAccount Token, TLS 검증 |
|---|---|
| 연결 테스트 | /version → 전체 또는 지정 namespace의 Pod 1건 조회 → 응답시간 |
| 수집 | Pod 메타데이터와 NodeName을 최대 500건 읽어 서버에 연결하며 cluster를 변경하지 않습니다. |
AI Provider
| 입력 | OpenAI-compatible Base URL, API Key, model, 최대 token(최대 262,144), TLS 검증 |
|---|---|
| 연결 테스트 | /models 조회로 주소·key·모델 목록 접근 확인 |
| 저장 후 | 비민감 시험 질문으로 stream: true SSE passthrough를 확인합니다. DB·Prometheus 자료는 자동 첨부하지 않습니다. |
Webhook
| 입력 | URL, 인증 Secret, 전달 이벤트 목록 |
|---|---|
| 연결 테스트 | Bearer 인증을 포함한 비식별 jupiq.integration.test POST의 2xx 응답과 소요시간 |
| 현재 버전 범위 | 연결 설정과 시험 전달입니다. 등록한 운영 이벤트의 자동 Webhook 발송은 향후 확장 범위입니다. |
선택형 모니터링
사용자별 자원 사용량 추적
JupyterHub 파드의 CPU·메모리 표본은 사용률입니다. 표본의 평균은 "실행 중 얼마나 바빴는가"를 말할 뿐이어서, 1 Core를 하루 점유한 사용자와 5분 점유한 사용자가 똑같이 1.0으로 보입니다. 누가 얼마나 썼는가는 점유량을 시간으로 적분해야 나옵니다.
수집기는 30초 주기 표본을 시간 단위 버킷으로 적분해 사용자·Hub별 core-seconds와 byte-seconds로 누적합니다. 화면과 API는 이를 Core·h와 GB·h로 보여 줍니다. 2 Core를 5시간 점유하면 10 Core·h입니다.
| 항목 | 내용 |
|---|---|
| 화면 | 비용·용량의 측정된 자원 사용량(사용자·Hub·망·부서별), 사용자 상세의 일·주·월 사용량 |
| API | GET /api/v1/usage/consumption?group_by=user|hub|network|department |
| 보존 | 원시 표본은 raw_retention_days(기본 30일), 사용량 집계는 usage_retention_days(기본 365일). 표본이 삭제된 뒤에도 집계는 남습니다. |
| 관측 비율 | 해당 구간 실행시간 중 표본이 실제로 관측된 비율. 낮으면 적게 썼다가 아니라 수집이 끊겼다는 뜻입니다. |
수집이 끊긴 구간은 적게 집계됩니다. 표본 하나가 대표할 수 있는 시간에 상한을 두기 때문에, 수집기나 Prometheus가 중단된 동안의 사용량은 과다 계상되는 대신 누락됩니다. 정산에 쓰기 전에 관측 비율을 함께 확인하세요. 진행 중인 시간대는 집계에 포함되지 않으며, 화면에 집계 완료 시각을 표시합니다.
초기 기본값은 OFF입니다. OFF이면 해당 수집, Prometheus query, API background job, 메뉴, 대시보드 KPI가 모두 비활성입니다. 기존 수집 자료는 보존 정책까지 남고 OFF 기간을 0으로 채우지 않습니다. 기능 오류는 Hub·인증·정책 등 본 서비스에 영향을 주지 않습니다.
GPU 모니터링 ON 절차
- 전제 확인
대상 GPU Node에 NVIDIA DCGM Exporter가 있고 Prometheus가 Pod label과 DCGM 지표를 수집해야 합니다. - Prometheus 연결 테스트
기본 연결 테스트는vector(1)query 권한을 확인합니다. DCGM 지표 존재 여부는 Prometheus에서 별도로 점검합니다. - 기본 query 확인
collector는DCGM_FI_DEV_GPU_UTIL의 Pod별 장치 수·평균과DCGM_FI_DEV_FB_USED기반 VRAM byte를 조회합니다. - ON 저장
GPU 메뉴·KPI가 나타나고 첫 수집 시각과 사용자/Pod 연결 여부를 확인합니다.
OFF로 돌릴 때는 수집과 UI만 중단하며 과거 GPU 통계는 삭제하지 않습니다. 삭제는 별도의 위험 작업과 보존 정책으로만 수행합니다.
LLM Chat Completions 사용량 ON 절차
API Gateway 또는 Service Mesh가 최소 pod, path, status 차원과 calls counter를 Prometheus에 노출해야 합니다. input/output token counter는 선택이며, 고 cardinality label보다 누적 counter를 권장합니다.
# 권장 metric 예시
http_requests_total{pod="jupyter-user01-...",path="/v1/chat/completions",status="200"}
http_request_bytes_total{pod="jupyter-user01-...",path="/v1/chat/completions"}
llm_prompt_tokens_total{pod="jupyter-user01-...",model="internal-model"}
llm_completion_tokens_total{pod="jupyter-user01-...",model="internal-model"}
# pod 이름 → 사용자 매핑 정규식 예시
^jupyter-(?P<username>[a-z0-9][a-z0-9-]{0,62})-.*$- 데이터 최소화 확인
Prometheus label에 prompt·response·authorization header가 없는지 검사합니다. - PromQL 설정
calls는 필수이며 latency·bytes·input/output/total token query는 선택입니다. - 정규식·label 샘플 검증
(?P<username>...)named capture와 Prometheus 결과의 canonicalpod·pathlabel을 테스트합니다. 결과가 비어 있으면 연결만 성공한 것이며 실제 귀속은 아직 검증되지 않은 것으로 표시됩니다. - 서버 인벤토리 대조
정규식은 후보 필터입니다. 실제 수집은 JupyterHub/Kubernetes에서 확인한 현재servers.pod_name과 정확히 일치할 때만 DB의 서버 소유자에게 귀속하며, 알 수 없거나 망 간 중복된 Pod는 제외합니다. - label·비용 설정
canonical label mapping, Chat Completions 경로, 100만 token당 input/output 단가와 보존일을 정합니다. - ON 저장
첫 수집의 username→Pod→model별 calls·성공률·P95와 신선도를 확인합니다.
token 메트릭이 없으면 화면은 해당 token을 수집 불가로 표시하고 추정하지 않습니다. LLM 수집 실패는 AI API 호출 자체를 차단하지 않습니다.
운영 카탈로그와 선택적 승인 Workflow
정책·Profile·Image·프로젝트·Incident·알림·비용 메뉴는 운영 정보를 등록·조회·수정·삭제하는 CRUD 카탈로그입니다. 현재 버전에서는 카탈로그 값이 JupyterHub·Kubernetes 자원을 자동 변경하거나 Quota·Idle·예약을 집행하지 않습니다.
| 영역 | 현재 버전 동작 |
|---|---|
| 운영 카탈로그 | 이름·상태와 유형별 상세 필드 CRUD |
| 서버 동작 | 시작·중지·재시작 직접 실행 또는 승인 요청 생성 |
| 팀장 선검토 | 설정 시 pending_review 요청을 검토 권한자가 다음 단계로 이동하며 요청자 본인 검토는 차단 |
| 승인·반려 | 요청자와 다른 승인 권한자가 처리하고, 선검토를 사용한 요청은 검토자와도 다른 승인자가 승인할 때 서버 동작 실행 |
승인 Workflow가 꺼져 있으면 승인 메뉴를 숨기고 서버 동작을 권한 범위에서 즉시 실행합니다. Quota enforcement, Idle 자동 종료, GPU 예약·Fair Share, Configuration Drift와 변경 Preview는 향후 확장 범위입니다.
역할, 객체 범위와 키 관리
roles:read/roles:write permission이 있는 관리자는 설정 화면에서 역할 키·표시 이름·설명·permission을 관리하고 사용자별 역할 할당을 전역 또는 제한 범위로 저장할 수 있습니다. 기존 역할 할당은 업그레이드 후에도 전역으로 유지됩니다. 기본 시스템 역할은 super_admin과 user입니다.
| 범위 | 판정 | 지원 API |
|---|---|---|
| 전역 | 해당 permission의 모든 대상 | 모든 기존 API |
| Hub | 지정한 Hub ID 중 하나 | Hub 목록·상세·수정·삭제·연결 테스트·동기화, 사용자·서버 목록과 서버 제어 |
| 부서 | 동기화된 사용자의 부서명 중 하나 | 사용자·서버 목록과 서버 제어 |
| Hub + 부서 | Hub와 부서를 모두 만족(AND) | 사용자·서버 목록과 서버 제어 |
같은 종류의 여러 값은 OR, Hub와 부서처럼 다른 종류는 AND이며, 여러 역할 할당은 OR로 합칩니다. 제한 범위는 최소 한 개 조건이 필수입니다. 새 Hub 생성, 설정·역할·서비스 계정·감사·대시보드·사용량·메트릭·GPU·운영 카탈로그·통합 검색·MCP는 현재 버전에서 객체 범위를 완전히 필터링하지 않으므로 전역 permission만 허용합니다. 부서만 지정한 역할로 Hub 자체를 수정할 수 없습니다.
최고 관리자 보호: 활성 사용자의 전역 * 할당만 생존 최고 관리자로 계산합니다. 범위 제한 *는 마지막 최고 관리자를 대체하지 않습니다. 또한 제한 할당이 있는 사용자에게 구형 role_ids API를 보내면 전역 승격을 막기 위해 거부됩니다.
개인 키는 사용자가 개인화 → API 키·회전에서 생성·회전·폐기하고, 관리자는 기본 회전일, 최대 수명과 허용 scope를 설정합니다. API 키 permission은 사용자 역할의 전역·객체 범위와 교집합으로 계산되므로 키의 *도 사용자의 Hub·부서 범위를 넓히지 못합니다. 회전 시 이전 키는 즉시 폐기되며 rate limit이나 grace overlap은 현재 버전에 없습니다. 연동 비밀은 관리자 설정에서 별도로 관리하고 평문을 재표시하지 않습니다.
일상 운영 체크
- 대시보드에서 Stale 자료, SSE 연결과 Hub healthy/degraded 상태 확인
- Hub 사용자·서버 동기화와 CPU core·메모리 byte 기준 시각 확인
- 선택 기능을 켠 경우 GPU Util·VRAM 또는 LLM calls·P95·token 신선도 확인
- 감사로그에서 설정 변경, 서버 동작, 승인과 개인 키 작업 결과 확인
- 원시 메트릭·LLM 보존일과 개인 키 만료·회전 예정 확인
- PostgreSQL과
ENCRYPTION_KEY백업 복원, Bootstrap/OIDC 장애 접근 정기 훈련