# 컨테이너 관리

GPU 개발 환경(컨테이너)을 만들고 들어가는 방법을 자세히 설명합니다.

용어가 낯설다면 먼저 [핵심 개념](/getting-started/concepts.md)을 펼쳐 두세요.

---

## 컨테이너 만들기는 어디에서?

컨테이너 만들기는 **홈 화면(클러스터 예약)의 노드 카드를 누르는 것**으로만 시작합니다. 위쪽 메뉴의 **컨테이너** 페이지는 목록과 상세 보기만 제공하며, 만들기 버튼은 없습니다.

순서:

1. 로그인 → 자동으로 홈(클러스터 예약) 화면
2. 노드 카드를 누름
3. **컨테이너 시작** 창이 열림

---

## 컨테이너 목록 (조회 전용)

위쪽 메뉴에서 **컨테이너**를 누르면 우리 그룹의 컨테이너가 한 줄씩 보입니다.

| 열 | 어떤 값 |
|----|---------|
| 이름 | 누르면 상세 화면으로 이동 |
| 상태 | 지금 어떤 상태인지 |
| 사용자 | 누가 만들었는지 |
| 그룹 | 어느 그룹에 속하는지 |
| 작업 | 빠른 접속 (VS Code · SSH · Jupyter) / 삭제 |

**상태 / 사용자 / 그룹** 열을 누르면 그 값으로 걸러 볼 수 있는 드롭다운이 나옵니다. **이름** 열은 누르면 정렬됩니다.

### 상태 색

| 상태 | 색 | 의미 |
|------|----|------|
| Creating | 파랑 | 만드는 중 |
| Pending | 옅은 파랑 | 어디서 띄울지 정해지길 기다리는 중 |
| Running | 초록 | 정상 동작 |
| Deleting | 노랑 | 정리 중 |
| Stopped | 회색 | 멈춤 |
| Failed | 빨강 | 오류 (이미지를 못 가져오거나, 안에서 죽거나) |
| Completed | 남보라 | 정상적으로 끝남 |

---

## 컨테이너 시작 — 두 가지 진입

홈 화면에서 노드 카드를 누르면 열리는 창에 두 가지 진입점이 있습니다.

### 1) 템플릿으로 시작 (가장 빠른 길)

창 위쪽에 우리 그룹의 저장된 템플릿이 카드로 보입니다. 카드에는 템플릿 이름 · 이미지 · 인스턴스 종류(예: `A100 × 1`) · 공유 메모리 · 마운트 개수가 함께 적혀 있습니다.

1. 원하는 카드를 누릅니다.
2. 확인 창에서 컨테이너 이름을 적습니다.
3. **생성**을 누르면 바로 만들어집니다.

!!!note 템플릿 지우기
카드 위에 마우스를 가져가면 휴지통 아이콘이 보입니다. 누르면 삭제 확인 창이 뜹니다. (수정 기능은 아직 없습니다. 같은 설정으로 새로 만들고 다시 저장하세요.)
!!!

!!!warning 못 쓰는 템플릿
템플릿이 기억하던 스토리지 중 하나라도 사라졌다면 컨테이너를 만들 수 없습니다. 카드에 "스토리지 누락" 표시가 뜨고, 없어진 스토리지 이름을 알려 줍니다.
!!!

### 2) 새로 시작 (직접 고르기)

창 안쪽 **또는 새로 시작** 영역에서 인스턴스를 골라 두 단계로 진행합니다.

#### Step 1 — 인스턴스 고르기

노드에 실제로 남아 있는 자원을 보고 자동으로 만들어진 인스턴스 목록에서 고릅니다.

- GPU 수 × 노드 사정에 맞춘 CPU · 메모리
- GPU가 없는 노드는 CPU만 쓰는 인스턴스가 보입니다.
- GPU가 있는 노드는 GPU를 1개 이상 쓰는 인스턴스만 보입니다.

**다음**을 누르면 그 자원이 본인 앞으로 **5분간 잠시 잡혀** 있습니다. 그 안에 Step 2를 끝내야 합니다.

#### Step 2 — 옵션 설정 (5단계)

Step 2 안에 다시 다섯 개의 단계가 있습니다. 위쪽 진행 표시줄에서 어디까지 왔는지 확인할 수 있습니다.

| 단계 | 무엇을 |
|------|--------|
| **기본 정보** | 컨테이너 이름, 베이스 이미지 |
| **스토리지** | 마운트할 스토리지 (선택) |
| **운영 옵션** | 사용 시간 · 공유 메모리 · 환경 변수 · NUMA 옵션 |
| **템플릿** | 이 설정을 다음에 또 쓸 수 있게 저장할지 (선택) |
| **확인** | 설정을 다시 한 번 보고 **생성** |

#### 기본 정보 — 이미지 고르기

세 가지 중 하나를 고릅니다.

| 방법 | 어떤 식 |
|------|---------|
| 직접 입력하기 | Docker Hub 같은 공개 이미지 주소를 그대로 적기 |
| 레지스트리에서 이미지 선택 | 관리자가 등록해 둔 사내 저장소에서 찾기 |
| 커스텀 이미지 | 본인이 등록해 둔 이미지에서 고르기 |

자세한 내용은 [이미지 관리](./image.md)에서 확인합니다.

#### 스토리지 — 마운트

기존 스토리지를 컨테이너 안 어떤 경로에 붙일지 정합니다. 한 컨테이너에 여러 스토리지를 동시에 붙일 수 있습니다.

```
스토리지: my-dataset
마운트 경로: /workspace/data
```

스토리지가 없으면 같은 화면에서 **새 스토리지 만들기** 로 바로 만들 수 있습니다.

#### 운영 옵션 — 사용 시간

컨테이너에 만료 시간을 정합니다. 만료되면 자동으로 정리되어 GPU가 풀려납니다.

| 보기 |
|------|
| 1시간 · 4시간 · 1일 · 7일 · 30일 · 제한 없음 |

#### 운영 옵션 — 공유 메모리 (`/dev/shm`)

PyTorch DataLoader 같은 멀티프로세스 작업에서 자주 필요합니다.

- 기본은 비활성 (K8s 기본값 약 64 MB)
- 활성으로 켜면 GB 단위로 직접 정함
- 최댓값은 인스턴스 메모리에 따라 자동으로 결정

#### 운영 옵션 — 환경 변수

이름과 값을 짝지어 원하는 만큼 추가합니다.

#### 운영 옵션 — NUMA 옵션

켜면 같은 NUMA 노드 안에서만 CPU를 잡아, 메모리 접근 지연을 줄입니다. 큰 연산이 도는 워크로드에서 성능에 도움이 됩니다.

#### 템플릿 — 어떻게 저장할지

| 선택 | 동작 |
|------|------|
| 안 함 | 컨테이너만 만들고 끝 |
| 컨테이너 + 템플릿 | 컨테이너도 만들고, 같은 설정을 그룹 공유 템플릿으로도 저장 |
| 템플릿만 | 컨테이너는 만들지 않고 템플릿만 저장 |

저장 시 이름과 짧은 설명을 적습니다. 마운트한 스토리지도 그대로 기록됩니다.

!!!note 접속 포트는 항상 자동
VS Code(8443) · SSH(22) · JupyterLab(8888) 세 가지가 미리 준비됩니다. 사용자가 따로 정할 필요가 없습니다.
!!!

!!!note 비밀번호도 자동으로 받습니다
컨테이너마다 비밀번호가 자동으로 만들어집니다. SSH · VS Code · Jupyter 모두 이 한 비밀번호로 들어갑니다. 상세 화면에서 확인할 수 있습니다.
!!!

!!!warning 그룹 한도를 넘으면 만들 수 없습니다
홈 화면의 **그룹 가용 GPU** 카드에서 우리 그룹의 남은 자원을 먼저 확인하세요. CPU · 메모리 · 스토리지 한도는 인스턴스 카드와 스토리지 만들기 화면에서 그때그때 알려 줍니다.
!!!

---

## 컨테이너 상세 화면

목록에서 이름을 누르면 상세 화면으로 들어갑니다.

### 컨테이너 정보

| 항목 | 어떤 값 |
|------|---------|
| 컨테이너 이름 | 식별용 이름 |
| 상태 | 지금 상태 |
| 컨테이너 ID | 내부 식별자 |
| 컨테이너 이미지 | 지금 쓰는 이미지 |
| 인스턴스 | CPU · 메모리 · 가속기 |
| 소유자 | 만든 사람 |
| 그룹 | 소속 그룹 |
| 마운트된 스토리지 | 붙어 있는 스토리지 목록 |
| 환경 변수 | 들어가 있는 변수 목록 |
| 남은 시간 | 만료까지 얼마나 남았는지 (제한 없는 컨테이너는 "제한 없음") |

### 사용량 게이지

상세 화면에는 두 가지 사용량 막대가 항상 보입니다.

| 게이지 | 무엇 |
|--------|------|
| 메모리 | 인스턴스 메모리 대비 현재 사용량 |
| 루트 디스크 | 컨테이너 안 루트 파일시스템 사용량 |

75%가 넘으면 노랑, 90%가 넘으면 빨강으로 강조됩니다.

### 접속 카드

상세 화면 위쪽에 접속 카드 세 개가 있습니다.

| 카드 | 어떻게 동작 |
|------|------------|
| **VS Code** | 브라우저에서 code-server를 엽니다. 그게 안 돌고 있으면 PC에 설치된 VS Code Desktop이 SSH로 들어가도록 폴백 |
| **SSH** | PC의 터미널 앱이 뜨면서 SSH 명령어가 클립보드에 복사됩니다 |
| **Jupyter** | 브라우저에서 JupyterLab을 엽니다 |

각 카드의 색이 서비스 준비 상태를 알려 줍니다. **포트 미할당** · **준비 중** · **접속 가능** 으로 구분됩니다.

### SSH 접속 정보 + 자동 비밀번호

상세 화면의 **SSH 접속 정보** 영역에는 SSH 접속 명령어와 자동 발급 비밀번호가 함께 보입니다.

```bash
# 예시
ssh -p <포트번호> root@<노드IP>
```

이 비밀번호는 SSH · VS Code · Jupyter 어디서든 같은 값을 씁니다. 복사 버튼으로 클립보드에 담아 쓰면 됩니다.

!!!note 컨테이너 안에서 그 서비스가 실제로 돌고 있어야 합니다
포트는 자동으로 열리지만, 안에서 code-server · SSH 서비스 · JupyterLab이 켜져야 카드 버튼이 동작합니다. 권장 base image 빌드 안내는 [이미지 가이드](./image.md)와 [base image 빌드 가이드](https://github.com/bricksum/cluma/blob/main/docs/container-base-image-420.md)를 참고하세요.
!!!

!!!warning VS Code Desktop 폴백 조건
- PC에 VS Code Desktop이 설치되어 있어야 합니다.
- [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) 확장도 설치되어 있어야 합니다.
!!!

### Pod 진단

**Pod 진단 조회** 버튼을 누르면 Kubernetes 쪽에서 본 진짜 상태를 살펴볼 수 있습니다. 컨테이너가 안 뜰 때 원인 찾기에 가장 좋은 기능입니다.

| 항목 | 어떤 정보 |
|------|----------|
| 진행 상태 (Phase) | 대기 / 실행 / 완료 / 실패 |
| 노드 | 어디에 떠 있는지 |
| Pod IP | 클러스터 내부 IP |
| 상태 조건 | 스케줄링 완료, 초기화, 컨테이너 준비, 전체 준비 |
| 컨테이너별 상태 | 준비 여부, 재시작 횟수 |
| 이벤트 | Kubernetes가 남긴 최근 이벤트 목록 |

본인이 만든 컨테이너만 볼 수 있습니다 (관리자는 모두).

### 로그 보기

상세 화면의 **로그 보기**를 누르면 컨테이너 표준 출력이 거의 실시간으로 보입니다.

### 접속 포트 안내

표준 접속 포트(`vscode` / `ssh` / `jupyter`)의 외부 접속 주소(`노드IP:포트`)와 안쪽 포트 번호가 보기 전용으로 표시됩니다.

!!!note 표준 접속 포트는 손댈 수 없습니다
v1.1부터 표준 접속 포트는 자동으로만 관리되며, 사용자가 더하거나 지울 수 없습니다. 옛 사용자 정의 포트 기능은 v1.2에서 완전히 사라질 예정입니다.
!!!

---

## 컨테이너 지우기

목록의 삭제 아이콘이나 상세 화면의 **컨테이너 삭제** 버튼을 누릅니다.

확인 창에서 컨테이너 이름을 직접 다시 적어야 삭제가 풀립니다.

!!!danger 안에 있는 자료는 모두 사라집니다
컨테이너 안 자료는 지우는 순간 모두 없어집니다. 남기고 싶은 자료는 미리 스토리지에 옮겨 두세요.
!!!

---

## 다음 단계

- [스토리지 관리](./storage.md) — 자료를 영구 보관하는 법
- [이미지 관리](./image.md) — 내 이미지 등록과 권장 이미지
- [트러블슈팅](/troubleshooting/index.md) — 자주 겪는 문제와 해결