Nodemanager: Difference between revisions

From HPCWIKI
Jump to navigation Jump to search
(Add Drivers (GPU driver remote update) section — API, user flow, limitations)
(Redirect to Manual:Nodemanager)
Tag: New redirect
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
= nodemanager =
#redirect [[Manual:Nodemanager]]
 
== Overview ==
 
HPCMATE의 노드 원격 관리 웹 콘솔. 일반 사용자가 웹 브라우저에서 Linux 노드를 모니터링하고 관리할 수 있습니다.
 
=== 요약 ===
* 무엇인가: Linux 노드 모니터링 + 원격 관리 WebUI (Node.js + Express + WebSocket + RequireJS)
* 왜 필요한가: SSH 없이 웹에서 노드 상태 확인, 계정/패키지/컨테이너 관리, 감사 로그 조회
* 언제 사용하는가: HPCMATE 노드/클러스터 운영 · GPU 서버 모니터링 · 원격 관제
 
=== 조사 정보 ===
* 작성일: 2026-10-17 · '''수정:''' 2026-10-22
* 버전: v0.1.0 (Phase 9 S2 + Docker Mapping + BMC + Log Analysis)
* 다음 업데이트: Phase 9 S2(크로스노드 실시간) 구현 시
 
== Purpose ==
* Goal: SSH 없이 웹에서 노드 전체(성능·계정·패키지·컨테이너·저장·로그·감사)를 관리
* Scope: 단일 노드 원격 관리 + 멀티노드 레지스트리(Phase 9 S1)
* Non-goals: 원격 명령 평면(S3), 클러스터 오케스트레이션(K8s), GPU 조도 관리
 
== Key Concepts ==
{| class="wikitable"
! 개념 ! 설명 ! 관련
|-
| node-scoped | topic/REST/DB에 노드 차원(`self`) 포함 — 멀티노드 전환 시 마이그레이션 없음 | [[Server]]
|-
| WS relay | 서버 측 수신자별 필터 — 비admin은 권한 밖 토픽 drop(fail-closed) | [[Network]]
|-
| cmd/runner | 특권 명령 단일 직렬 큐 — shell 불경유(arg 배열) 인젝션 차단 | [[Linux]]
|-
| RBAC | admin(`nm-admin` 그룹) vs user(읽기 + 매핑된 Docker 리소스) | [[Linux]]
|-
| lic/ (stub) | 현재 community tier, maxNodes=1 — 실 구현은 독립 라이선스 프로그램 연계 예정 | [[Server]]
|}
 
== Architecture ==
 
<syntaxhighlight lang="text">
Browser (RequireJS, eventemitter3 bus)
        ⇄  WebSocket /ws?token=  +  REST /api
Node Server
  ├─ collectors/    (2s/5s 주기, systeminformation / nvidia-smi)
  ├─ bus            (EventEmitter — 모든 데이터의 hub)
  ├─ ws.js          (relay — 수신자별 서버 측 필터)
  ├─ svc/            (users | packages | services | docker | quotas | mapping | nodes)
  ├─ cmd/runner      (특권 명령 단일 직렬 큐, arg 배열만)
  ├─ lic/            (라이선스 인터페이스, stub: community/1node)
  └─ db              (SQLite: nodes, audit, tokens, mappings, quotas)
</syntaxhighlight>
 
== Views (화면) ==
 
=== 로그인 ===
노드 로컬 계정으로 로그인 (실 shadow 검증).
 
[[File:12-login.png|400px|로그인 화면]]
 
=== Dashboard ===
실시간 성능 모니터링. CPU·메모리·GPU(4개, 색상별)·네트워크(2 인터페이스)·파일시스템·상위 프로세스를 실시간 차트로 표시.
 
[[File:1-dashboard.png|800px|Dashboard — 실시간 CPU/GPU/네트워크/프로세스 모니터링]]
 
=== Users ===
로컬 계정 CRUD. 계정 생성/수정/삭제, 비밀번호 설정, 잠금/해제. root는 WebUI에서 보호됨.
 
[[File:2-users.png|800px|Users — 계정 관리]]
 
=== Packages / Services ===
패키지 검색·설치·업그레이드·제거 (apt/dnf/yum/pacman/apk 자동 감지) + systemd 서비스 관리 (start/stop/restart/enable/disable). 작업 진행도는 WebSocket으로 실시간 스트리밍.
 
[[File:3-packages.png|800px|Packages/Services — 패키지·서비스 관리]]
 
=== Docker ===
컨테이너/이미지 CRUD. pull 진행도, 실시간 상태·로그. dockerode 경유.
 
[[File:4-docker.png|800px|Docker — 컨테이너·이미지 관리]]
 
=== Docker Mapping ===
사용자 ↔ 컨테이너/이미지 접근 권한 매핑 (view / exec / manage). 비admin의 Docker 접근 통로.
 
[[File:5-mapping.png|800px|Docker Mapping — 사용자↔리소스 접근 권한]]
 
=== Storage Quota ===
사용자별 저장 공간 할당·사용량·한도. 80%/90%/100% 초과 시 알림.
 
[[File:6-storage.png|800px|Storage Quota — 사용자별 할당·한도]]
 
=== Logs / Security ===
journalctl 실시간 스트리밍 + 보안 이벤트 피드 (로그인 실패, 403, 스로틀). admin 전용.
 
[[File:7-logs.png|800px|Logs/Security — 실시간 로그·보안 이벤트]]
 
=== Log Analysis ===
수집된 로그를 패턴으로 디코딩 — OOM, 디스크 I/O, segfault, 유닛 실패, 마운트, 네트워크, 인증 오류를 감지하고 한국어 진단 + 권장 조치를 제공.
 
[[File:8-loganalysis.png|800px|Log Analysis — 패턴 디코딩 + 진단·권장 조치]]
 
=== BMC ===
기본 관리 컨트롤러(BMC) 접근. 이노텍 [[DCIM]] 등.
 
[[File:9-bmc.png|800px|BMC — 기본 관리 컨트롤러]]
 
=== Audit ===
관리 작업 감사 로그 (15초 자동 갱신). 로그인 성공/실패, 계정/패키지/컨테이너/쿼터/매핑/노드 작업 전부 기록.
 
[[File:10-audit.png|800px|Audit — 감사 로그]]
 
=== Nodes (Phase 9 S1) ===
멀티노드 레지스트리 + 라이선스 관리 + 온보딩. 라이선스 상한 내 노드 등록, 10초 주기 health 프로브, 실시간 상태.
 
[[File:11-nodes.png|800px|Nodes — 멀티노드 레지스트리·라이선스]]
 
== Roles & RBAC ==
{| class="wikitable"
! 리소스 ! user (비admin) ! admin
|-
| Dashboard (metrics/alerts) | ✅ | ✅
| Packages/Services 읽기 | ✅ | ✅
| Packages/Services 변경 | ❌ 403 | ✅
| Docker list/stats/logs | ✅ (매핑된 리소스만) | ✅ 전체
| Docker 이미지 제거 | ❌ 403 | ✅
| Users / Mapping / Quotas / Audit | ❌ 403 | ✅
| Nodes (레지스트리) | ❌ 403 | ✅
|}
 
* 인증: 로컬 노드 계정 (pam → python3 shadow 폴백)
* 세션: 32B 랜덤 토큰, TTL 기본 12시간
* 스로틀: 10분 내 실패 5회 → 60초 잠금 (429)
* WS: `/ws?token=...` — 토큰 부재/만료 시 close `4401`
 
== Deployment ==
 
=== 프로덕션 (Docker) ===
<syntaxhighlight lang="bash">
docker build -t nodemanager .
 
docker run -d --name nodemanager --privileged --net=host \
  -v nm-data:/var/lib/nodemanager \
  -v /var/run/docker.sock:/app/docker.sock \
  nodemanager
</syntaxhighlight>
 
* `--net=host` 필수 — host NIC 가시성 + `-p` 불필요
* GPU: `deploy/gpu/`에 바이너리+라이브러리 이미지에 베이킹 (재조성 시 소실 없음)
* 관리자: `docker exec nodemanager usermod -aG nm-admin <user>`
* WebUI: `http://<host>:8080`
 
=== 개발 (host mount) ===
<syntaxhighlight lang="bash">
docker run -i --rm --name nm-dev --privileged --net=host \
  -v $PWD/server:/app/server -v $PWD/public:/app/public -v $PWD/test:/app/test \
  -v /var/run/docker.sock:/app/docker.sock \
  -v /etc/passwd:/etc/passwd -v /etc/shadow:/etc/shadow -v /etc/group:/etc/group \
  nodemanager-dev
</syntaxhighlight>
 
* `NM_DEV_AUTH=1` — 계정 존재만으로 로그인 (프로덕션 image에는 미포함)
* `-i --rm` + host mount (CLAUDE.md: `-d` detached 개발 금지)
 
== API Summary ==
 
REST base: `http://<host>:<port>/api` (기본 포트 8080)
 
{| class="wikitable"
! 메서드 ! 경로 ! 역할 ! 설명
|-
| POST | `/login` | 공개 | `{username, password}` → `{token, user, role}`
|-
| GET | `/health` | 무인증 | `{ok, version, license, uptimeSec, ...}`
|-
| GET | `/users` | admin | 계정 목록
|-
| GET | `/packages?q=` | 인증 | 검색/설치 목록
|-
| GET | `/services` | 인증 | systemd 서비스 목록
|-
| GET | `/docker/containers` | 인증 | 컨테이너 목록 (비admin: 매핑 필터)
|-
| GET | `/audit?limit=` | admin | 감사 로그
|-
| GET | `/nodes` | admin | 노드 레지스트리 + 라이선스
|-
| POST | `/nodes` | admin | 노드 등록 (라이선스 slot 소모)
|}
 
WebSocket base: `/ws?token=<token>`
 
{| class="wikitable"
! 토픽 ! 주기 ! 가시성
|-
| `system.<node>.metrics` | 2초 | 전체
|-
| `system.<node>.alerts` | 이벤트 | 전체
|-
| `docker.<node>.containers` | 5초 | 비admin: 매핑 필터
|-
| `system.<node>.nodes` | 10초 + CRUD | admin 전용
|-
| `users.changed` | 이벤트 | admin 전용
|-
| `storage.<node>.usage` | 주기 | admin 전용
|}
 
== Best Practices ==
* Docker 컨테이너는 반드시 `--net=host` 사용 (host NIC/proc 가시성)
* docker.sock은 `/app/docker.sock`에 마운트 (systemd tmpfs 마스킹 회피)
* 관리자 계정은 `nm-admin` 그룹에 명시적 부여
* dev 환경에서는 `NM_DEV_AUTH=1` 사용 — 프로덕션 image에는 절대 포함 금지
* 업그레이드 시 `nm-data` 볼륨 유지 (DB 영속)
* GPU 라이브러리 업데이트: `deploy/gpu/update.sh` + 재빌드 + 컨테이너 재조성
 
== Limitations ==
* Phase 9 S2 (크로스노드 실시간 telemetry 브리징)는 **설계 완료, 구현 대기**
  — 노드 선택 대시보드, 원격 노드 CPU/GPU/네트워크 실시간 차트 아직 불가
* Phase 9 S3 (원격 명령 평면, 원격 exec)는 설계 미착수
* 라이선스 실 구현 (오프라인 서명 key + HWID 바인딩)은 독립 프로그램 연계 시점
* BMC 뷰는 DCIM 연동 상태에 따라 기능이 제한될 수 있음
 
== Drivers (GPU 드라이버 관리) ==
 
=== 요약 ===
* 무엇인가: GPU 드라이버 원격 관리 — 현재 버전 감지, repository에서 호환 업데이트 확인, 원클릭 업데이트
* 왜 필요한가: 사용자가 노트북에서 GPU 서버 드라이버를 SSH 없이 업데이트
* 언제 사용하는가: GPU 드라이버 업그레이드/다운그레이드, 드라이버 문제 해결(재설치)
 
=== 사용자 흐름 ===
 
# 로그인 → '''Drivers''' 메뉴 클릭
# 현재 드라이버 버전 + GPU 목록 자동 표시
# Available Updates 섹션에서 호환 버전 확인
# '''Update''' 버튼 클릭 → 확인 다이얼로그(GPU 프로세스/재부팅 경고)
# 진행바: Download → Verify → Stop services → Install → Verify → Done
# 완료 또는 "Reboot required" → Reboot now 버튼
 
=== API ===
{| class="wikitable"
! Endpoint
! Method
! 권한
! 설명
|-
| /api/driver
| GET
| auth
| 현재 드라이버 상태 (버전, GPU, 커널, OS)
|-
| /api/driver/updates
| GET
| auth
| repository에서 호환 업데이트 조회
|-
| /api/driver/update
| POST
| admin
| 드라이버 업데이트 실행 (비동기 job)
|-
| /api/driver/rollback
| POST
| admin
| 이전 버전으로 롤백
|-
| /api/driver/reboot
| POST
| admin
| 원격 재부팅
|-
| /api/driver/preflight
| GET
| auth
| 사전 검사 (디스크, headers, GPU 프로세스)
|}
 
=== 제한점 및 해결 ===
{| class="wikitable"
! 제한점
! 해결
|-
| Repository auth (401)
| data/repo.json에 토큰 저장 (serversetup provisioning 시 배포)
|-
| Self-signed TLS
| repo 호출만 NODE_TLS_REJECT_UNAUTHORIZED=0 (내부 네트워크)
|-
| [[Kernel]] headers 부재
| pre-flight에서 자동 apt-get install linux-headers
|-
| Reboot 필요
| post-install detect → UI에 "Reboot now" 버튼
|-
| GPU 프로세스 충돌
| nvidia-persistenced stop + 경고 다이얼로그
|-
| 디스크 공간 (3-5GB)
| pre-flight: df 체크 (2x driver size)
|-
| Rollback
| 이전 버전 마커 보관 + repo에서 재다운로드
|}
 
=== 설정 ===
 
<syntaxhighlight lang="json">
// data/repo.json (serversetup이 provisioning 시 배포)
{"url": "https://repository.hpcmate.com", "token": "<redacted>"}
</syntaxhighlight>
 
== References ==
 
== References ==
* 프로젝트: `~/work/nodemanager` (git.hpcmate.com)
* API 전체: [API.md](git.hpcmate.com)
* 배포: [DEPLOY.md](git.hpcmate.com)
* 설계: [[[Plan|PLAN]].md](git.hpcmate.com)
* HPCMATE: [http://www.hpcmate.com](http://www.hpcmate.com)
 
== Related Pages ==
* [[Docker]]
* [[Docker Mapping]]
* [[systemd]]
* [[GPU]]
* [[Network]]
* [[Linux]]
* [[Server]]
* [[HPC]]
 
[[Category:Server]]
[[Category:Guide]]

Latest revision as of 09:21, 23 October 2026

Redirect to:

Retrieved from "http://wiki.hpcmate.com/index.php?title=Nodemanager&oldid=4192"