Nodemanager

From HPCWIKI
Revision as of 18:33, 17 October 2026 by Clara (talk | contribs) (Create nodemanager manual page with 12 view screenshots (Phase 9 S1))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

nodemanager

Overview

HPCMATE의 노드 원격 관리 웹 콘솔. 일반 사용자가 웹 브라우저에서 Linux 노드를 모니터링하고 관리할 수 있습니다.

요약

  • 무엇인가: Linux 노드 모니터링 + 원격 관리 WebUI (Node.js + Express + WebSocket + RequireJS)
  • 왜 필요한가: SSH 없이 웹에서 노드 상태 확인, 계정/패키지/컨테이너 관리, 감사 로그 조회
  • 언제 사용하는가: HPCMATE 노드/클러스터 운영 · GPU 서버 모니터링 · 원격 관제

조사 정보

  • 작성일: 2026-10-17
  • 버전: v0.1.0 (Phase 9 S1 완료 상태)
  • 다음 업데이트: Phase 9 S2(크로스노드 실시간) 구현 시

Purpose

  • Goal: SSH 없이 웹에서 노드 전체(성능·계정·패키지·컨테이너·저장·로그·감사)를 관리
  • Scope: 단일 노드 원격 관리 + 멀티노드 레지스트리(Phase 9 S1)
  • Non-goals: 원격 명령 평면(S3), 클러스터 오케스트레이션(K8s), GPU 조도 관리

Key Concepts

개념 ! 설명 ! 관련
topic/REST/DB에 노드 차원(`self`) 포함 — 멀티노드 전환 시 마이그레이션 없음 | Server
서버 측 수신자별 필터 — 비admin은 권한 밖 토픽 drop(fail-closed) | Network
특권 명령 단일 직렬 큐 — shell 불경유(arg 배열) 인젝션 차단 | Linux
admin(`nm-admin` 그룹) vs user(읽기 + 매핑된 Docker 리소스) | Linux
현재 community tier, maxNodes=1 — 실 구현은 독립 라이선스 프로그램 연계 예정 | Server

Architecture

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)

Views (화면)

로그인

노드 로컬 계정으로 로그인 (실 shadow 검증).

로그인 화면

Dashboard

실시간 성능 모니터링. CPU·메모리·GPU(4개, 색상별)·네트워크(2 인터페이스)·파일시스템·상위 프로세스를 실시간 차트로 표시.

Dashboard — 실시간 CPU/GPU/네트워크/프로세스 모니터링

Users

로컬 계정 CRUD. 계정 생성/수정/삭제, 비밀번호 설정, 잠금/해제. root는 WebUI에서 보호됨.

Users — 계정 관리

Packages / Services

패키지 검색·설치·업그레이드·제거 (apt/dnf/yum/pacman/apk 자동 감지) + systemd 서비스 관리 (start/stop/restart/enable/disable). 작업 진행도는 WebSocket으로 실시간 스트리밍.

Packages/Services — 패키지·서비스 관리

Docker

컨테이너/이미지 CRUD. pull 진행도, 실시간 상태·로그. dockerode 경유.

Docker — 컨테이너·이미지 관리

Docker Mapping

사용자 ↔ 컨테이너/이미지 접근 권한 매핑 (view / exec / manage). 비admin의 Docker 접근 통로.

Docker Mapping — 사용자↔리소스 접근 권한

Storage Quota

사용자별 저장 공간 할당·사용량·한도. 80%/90%/100% 초과 시 알림.

Storage Quota — 사용자별 할당·한도

Logs / Security

journalctl 실시간 스트리밍 + 보안 이벤트 피드 (로그인 실패, 403, 스로틀). admin 전용.

Logs/Security — 실시간 로그·보안 이벤트

Log Analysis

수집된 로그를 패턴으로 디코딩 — OOM, 디스크 I/O, segfault, 유닛 실패, 마운트, 네트워크, 인증 오류를 감지하고 한국어 진단 + 권장 조치를 제공.

Log Analysis — 패턴 디코딩 + 진단·권장 조치

BMC

기본 관리 컨트롤러(BMC) 접근. 이노텍 DCIM 등.

BMC — 기본 관리 컨트롤러

Audit

관리 작업 감사 로그 (15초 자동 갱신). 로그인 성공/실패, 계정/패키지/컨테이너/쿼터/매핑/노드 작업 전부 기록.

Audit — 감사 로그

Nodes (Phase 9 S1)

멀티노드 레지스트리 + 라이선스 관리 + 온보딩. 라이선스 상한 내 노드 등록, 10초 주기 health 프로브, 실시간 상태.

Nodes — 멀티노드 레지스트리·라이선스

Roles & RBAC

리소스 ! user (비admin) ! admin
✅ | ✅ ✅ | ✅ ❌ 403 | ✅ ✅ (매핑된 리소스만) | ✅ 전체 ❌ 403 | ✅ ❌ 403 | ✅ ❌ 403 | ✅
  • 인증: 로컬 노드 계정 (pam → python3 shadow 폴백)
  • 세션: 32B 랜덤 토큰, TTL 기본 12시간
  • 스로틀: 10분 내 실패 5회 → 60초 잠금 (429)
  • WS: `/ws?token=...` — 토큰 부재/만료 시 close `4401`

Deployment

프로덕션 (Docker)

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
  • `--net=host` 필수 — host NIC 가시성 + `-p` 불필요
  • GPU: `deploy/gpu/`에 바이너리+라이브러리 이미지에 베이킹 (재조성 시 소실 없음)
  • 관리자: `docker exec nodemanager usermod -aG nm-admin <user>`
  • WebUI: `http://<host>:8080`

개발 (host mount)

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
  • `NM_DEV_AUTH=1` — 계정 존재만으로 로그인 (프로덕션 image에는 미포함)
  • `-i --rm` + host mount (CLAUDE.md: `-d` detached 개발 금지)

API Summary

REST base: `http://<host>:<port>/api` (기본 포트 8080)

메서드 ! 경로 ! 역할 ! 설명
`/login` | 공개 | `{username, password}` → `{token, user, role}`
`/health` | 무인증 | `{ok, version, license, uptimeSec, ...}`
`/users` | admin | 계정 목록
`/packages?q=` | 인증 | 검색/설치 목록
`/services` | 인증 | systemd 서비스 목록
`/docker/containers` | 인증 | 컨테이너 목록 (비admin: 매핑 필터)
`/audit?limit=` | admin | 감사 로그
`/nodes` | admin | 노드 레지스트리 + 라이선스
`/nodes` | admin | 노드 등록 (라이선스 slot 소모)

WebSocket base: `/ws?token=<token>`

토픽 ! 주기 ! 가시성
2초 | 전체
이벤트 | 전체
5초 | 비admin: 매핑 필터
10초 + CRUD | admin 전용
이벤트 | admin 전용
주기 | 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 연동 상태에 따라 기능이 제한될 수 있음

References

  • 프로젝트: `~/work/nodemanager` (git.hpcmate.com)
  • API 전체: [API.md](git.hpcmate.com)
  • 배포: [DEPLOY.md](git.hpcmate.com)
  • 설계: [[[Plan|PLAN]].md](git.hpcmate.com)
  • HPCMATE: [1](http://www.hpcmate.com)

Related Pages

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