# 핵심 개념

이 페이지는 Cluma 안에서 쓰는 용어를 한 자리에 모아 설명합니다. 다른 문서에서 모르는 단어가 나오면 이곳을 펼쳐서 확인하시기를 권장합니다.

---

## 유저 (User)

Cluma에 로그인하는 사용자 계정입니다. 모든 유저는 **관리자** 또는 **일반 사용자** 중 하나의 역할을 갖습니다.

### 관리자 (Admin)

플랫폼 전체를 운영하는 사람입니다.

- 유저 만들기 · 고치기 · 지우기
- 그룹 만들기 · 고치기 · 지우기
- 유저를 그룹에 넣거나 빼기
- 전체 클러스터 사용 현황 보기
- 노드, 이미지 저장소 등 인프라 관리
- 모든 사용 이력(감사 로그) 조회

### 일반 사용자 (Regular User)

자기 그룹 안에서 작업하는 사람입니다.

- 소속 그룹의 한도 안에서 컨테이너 만들기
- 스토리지 만들기, 컨테이너에 붙이기
- 홈 화면에서 자기 그룹 가용량 확인
- 그룹 바꾸기는 직접 못 합니다 (관리자에게 요청)

---

## 그룹 (Group)

유저들을 묶고, 같이 쓸 자원의 상한선을 정해두는 단위입니다.

- 한 유저는 여러 그룹에 속할 수 있습니다. 화면 위쪽 **그룹 선택** 메뉴에서 지금 활성으로 쓸 그룹을 바꿉니다.
- 그룹마다 CPU, 메모리, GPU 등 가속기, 스토리지의 최대 용량을 정합니다.
- 새 유저는 처음에 `Default` 그룹에 자동으로 들어갑니다.
- 그룹은 Kubernetes 위에서 **별도의 작업 공간(네임스페이스)** 으로 분리됩니다. 다른 그룹과 자료가 섞이지 않고, 외부에서 임의로 들어올 수도 없습니다.

```
그룹 A (CPU: 32 코어 / 메모리: 128GB / GPU: 4개)
├── 유저 1
├── 유저 2
└── 유저 3
```

---

## 인스턴스 (Instance)

컨테이너를 만들 때 고르는 **CPU·메모리·GPU 묶음**입니다. 노드에 실제로 남아 있는 자원을 보고 Cluma가 자동으로 만들어 보여줍니다.

| 보기 |
|------|
| 노드가 CPU 16코어 · 메모리 125GB · GPU 3개를 갖고 있을 때 → GPU 1개를 쓰는 인스턴스 = CPU 5코어 · 메모리 41GB |

- 노드 정보가 없으면 GPU 1개당 CPU 4코어 · 메모리 16GB로 잡아 만듭니다.
- GPU가 없는 노드에는 CPU만 쓰는 인스턴스가 보입니다.
- GPU가 있는 노드에는 GPU를 1개 이상 쓰는 인스턴스만 보입니다.

!!!note 새 노드를 등록하거나 그룹 한도가 바뀌면
사용할 수 있는 인스턴스 목록도 자동으로 다시 계산됩니다.
!!!

---

## 컨테이너 (Container)

Cluma에서 실제로 작업하는 **GPU 개발 환경**입니다. Kubernetes의 배포 단위(Deployment) 위에서 동작해서, 노드 한 대가 잠시 꺼져도 다른 노드로 옮겨 다시 살아나는 안정성을 갖습니다.

### 구성 요소

| 항목 | 설명 |
|------|------|
| 이미지 | 어떤 환경을 띄울지 정하는 Docker 이미지 |
| 인스턴스 | CPU · 메모리 · GPU 묶음 |
| 표준 접속 포트 | VS Code · SSH · Jupyter — 자동 노출 |
| 사용 시간 | 1시간 / 4시간 / 1일 / 7일 / 30일 / 제한 없음 — 만료되면 자동 종료 |
| 스토리지 마운트 | 영구 보관할 폴더를 컨테이너 안 어떤 경로에 연결할지 |
| 공유 메모리 (Shared Memory) | `/dev/shm` 크기. PyTorch DataLoader 같은 멀티프로세스에서 자주 필요. 비활성 시 K8s 기본(약 64 MB) |
| 환경 변수 | 컨테이너가 시작할 때 넣어줄 값 |
| 자동 비밀번호 | 컨테이너마다 비밀번호가 자동으로 발급됩니다. SSH · VS Code · Jupyter가 같은 비밀번호를 씁니다. |

### 표준 접속 포트

새 컨테이너에는 세 가지 접속 길이 항상 미리 열려 있습니다. 사용자가 따로 설정할 필요가 없습니다.

| 이름 | 컨테이너 안 포트 | 용도 |
|------|----------------|------|
| `vscode` | 8443 | 브라우저에서 여는 VS Code (code-server) |
| `ssh` | 22 | SSH 터미널 접속 |
| `jupyter` | 8888 | 브라우저에서 여는 JupyterLab |

!!!warning 컨테이너 이미지 안에서 해당 서비스가 실행되어야 합니다
포트는 열려 있어도, 그 안에서 VS Code · SSH 서비스 · Jupyter가 실제로 켜져야 카드 버튼이 동작합니다. 권장 이미지는 [이미지 가이드](/user-guide/image.md)를 참고하세요.
!!!

### 사용 시간 (Expiry)

컨테이너는 만료 시간을 가집니다. 만료 시각이 되면 컨테이너가 자동으로 정리되어 GPU가 다른 작업으로 풀려납니다.

- 만들 때 1시간 / 4시간 / 1일 / 7일 / 30일 / 제한 없음 중에서 고릅니다.
- 상세 화면에 **남은 시간** 이 항상 표시됩니다 (90% 가까워지면 경고 색).
- 자료를 잃지 않으려면 스토리지에 옮겨 두세요.

---

## 템플릿 (Template)

자주 쓰는 컨테이너 설정을 그룹 안에서 공유하는 묶음입니다.

- 이미지 · 인스턴스 · 환경 변수 · 마운트한 스토리지 · 공유 메모리 설정이 그대로 저장됩니다.
- 그룹 멤버 누구나 템플릿을 골라 같은 환경을 한 번에 만들 수 있습니다.
- 템플릿이 기억하던 스토리지가 사라졌다면, 그 템플릿으로는 새 컨테이너를 만들 수 없습니다. 화면이 이유를 알려 줍니다.

---

## 스토리지 (Storage)

컨테이너가 사라져도 자료는 그대로 두기 위한 **영구 보관 공간**입니다. Kubernetes의 영구 저장소 단위 위에서 동작합니다.

### 스토리지 유형

관리자가 클러스터에 등록한 저장소 유형(NFS, Local 등) 중에서 골라 만듭니다.

### 접근 범위

- **Group**: 같은 그룹에 속한 사람이 모두 공유 (현재 기본값)

---

## 이미지 (Image)

컨테이너를 띄울 때 쓰는 Docker 이미지입니다.

- 관리자가 등록한 **이미지 저장소**에서 골라 쓸 수 있습니다.
- 외부에 공개된 이미지 주소를 직접 입력해서 쓸 수도 있습니다.
- 일반 사용자도 자기만의 이미지를 등록해서 재사용할 수 있습니다.

---

## 가속기 (Accelerator) / GPU 분할 (MIG)

Cluma는 NVIDIA GPU 외에도 다양한 가속기를 다룰 수 있게 **가속기 유형**이라는 한 단계 상위 개념으로 다룹니다.

- 그룹마다 가속기 유형별로 몇 개까지 쓸지 정합니다 (예: NVIDIA A100 4장).
- 인스턴스 카드에는 가속기 모델명과 개수가 함께 보입니다 (예: `A100 × 2`).
- NVIDIA의 **GPU 분할 기능(MIG, Multi-Instance GPU)** 을 켜면, GPU 한 장을 여러 조각으로 쪼개 여러 작업에 나눠 줄 수 있습니다.

---

## 보안 격리

그룹마다 작업 공간이 분리되면서, 두 가지 보호막이 자동으로 씌워집니다.

| 보호막 | 효과 |
|--------|------|
| 기본 보안 정책 | `hostNetwork` / `hostPort` / 특권(`privileged`) 같은 위험한 옵션을 쓰는 컨테이너를 거부 |
| 그룹 간 네트워크 차단 | 다른 그룹과 직접 통신 금지. 표준 접속 포트만 외부에서 열림 |

Cluma 안에서 만드는 일반 컨테이너에는 영향이 없고, 외부에서 임의로 매니페스트를 만들어 들이밀 때만 막힙니다.

---

## 감사 로그 (Audit Log)

누가 · 언제 · 무엇을 했는지 자동으로 기록되는 이력입니다.

- 로그인 / 로그아웃
- 컨테이너 · 스토리지 · 사용자 · 그룹 · 템플릿 · 이미지 저장소의 만들기·고치기·지우기
- 성공 여부, 결과 코드, 처리 시간

[감사 로그](/admin-guide/audit-logs.md) 페이지는 관리자만 볼 수 있습니다.

---

## 자주 나오는 용어 한눈에 보기

| 용어 | 의미 |
|------|------|
| 노드 (Node) | 클러스터를 구성하는 한 대의 서버 |
| Pod | 컨테이너가 실제로 실행되는 가장 작은 단위 |
| 인스턴스 | CPU · 메모리 · GPU 묶음. 컨테이너를 만들 때 고름 |
| 그룹 | 유저 + 자원 한도 묶음 |
| 작업 공간 (Namespace) | Kubernetes가 그룹마다 만드는 격리된 공간 |
| 스토리지 | 영구 보관 공간 |
| 가속기 | GPU 같은 연산 보조 장치 |
| 표준 접속 포트 | 컨테이너에 자동으로 열려 있는 VS Code · SSH · Jupyter 포트 |
| 사용 시간 | 컨테이너 만료까지 남은 시간. 만료되면 자동 정리 |
| 공유 메모리 | 컨테이너 안 `/dev/shm` 크기. 멀티프로세스 학습에 자주 늘림 |
| 작업 배치 제외 (Drained) | 새 작업을 더 이상 받지 않게 잠시 빼둔 노드 상태 |
| 감사 로그 | 누가 무엇을 했는지 자동으로 남는 이력 |

---

## 다음 단계

- [사전 요구사항](./prerequisites.md) — 설치 전 환경 점검
- [사용자 빠른 시작](./quickstart.md) — 컨테이너 만들기까지 가는 길
- [관리자 초기 설정](./admin-setup.md) — 그룹·유저·이미지 저장소 등록