service-catalog/manifests/helm/jupyterlab/1.0.0/CUSTOM-README.md

# custom-values.yaml 사용 가이드

이 문서는 `custom-values.yaml`을 작성하고 배포에 적용하는 방법을 설명합니다.

## Helm Values Merge 동작 방식

Helm은 `--values` 플래그로 전달된 파일을 기본 `values.yaml`에 **deep merge** 방식으로 적용합니다.

- `custom-values.yaml`에 명시된 키는 `values.yaml` 기본값을 **덮어씁니다**
- 명시하지 않은 키는 `values.yaml` 기본값이 **그대로 유지됩니다**
- 중첩 객체(`resources`, `ingress` 등)도 키 단위로 병합됩니다

```
values.yaml (기본값)
    +
custom-values.yaml (override)
    =
최종 적용값
```

## custom-values.yaml 필드 설명

### image

```yaml
image:
  registry: "quay.io"        # 레지스트리 주소. 비워두면 Docker Hub 사용

  # tag는 생략 가능. repository에 태그를 포함하면 tag 필드는 무시됨.
  # 방법1: repository에 태그 포함 (tag 불필요)
  repository: "jupyter/scipy-notebook:ubuntu-22.04"

  # 방법2: repository + tag 분리
  # repository: "jupyter/scipy-notebook"
  # tag: "latest"

  tag: "latest"              # repository에 ":"가 있으면 이 값은 무시됨
```

| 입력 | 결과 이미지 |
|------|------------|
| `repository: "repo:ubuntu-22.04"`, `tag: "latest"` | `quay.io/repo:ubuntu-22.04` (tag 무시) |
| `repository: "repo"`, `tag: "latest"` | `quay.io/repo:latest` |
| `repository: "repo"`, `tag: ""` | `quay.io/repo` |

> `image.pullPolicy`는 custom-values에 없으므로 `values.yaml` 기본값 `IfNotPresent` 적용

### resources

```yaml
resources:
  limits:
    cpu: "2000m"       # 최대 2 vCPU
    memory: "4096Mi"   # 최대 4 GiB
  requests:
    cpu: "500m"        # 예약 0.5 vCPU
    memory: "1024Mi"   # 예약 1 GiB
  gpu: ""              # GPU 사용 시: "1" (nvidia.com/gpu limits/requests에 동일하게 설정됨)
```

### jupyterConfig

```yaml
jupyterConfig:
  token: ""    # 비어 있으면 토큰 인증 비활성화
               # 값 설정 시 SHA-256으로 해시되어 ServerApp.password에 적용
```

### ingress

```yaml
ingress:
  enabled: true
  ingressClassName: "kong"
  annotations:
    cert-manager.io/cluster-issuer: "root-ca-issuer"
    cert-manager.io/duration: "8760h"
    cert-manager.io/renew-before: "720h"
    konghq.com/https-redirect-status-code: "301"
    konghq.com/protocols: "https"
  hosts:
    - host: "jupyter.example.com"   # 실제 도메인으로 변경 필수
      paths:
        - /
  tls:
    - hosts:
        - "jupyter.example.com"
      secretName: "jupyter-tls-secret"
```

### homeVolume / dataVolume

```yaml
homeVolume:
  enabled: false          # true로 설정 시 /home/jovyan에 PVC 마운트
  size: "5Gi"
  storageClassName: ""    # 클러스터 기본 StorageClass 사용
  accessMode: "ReadWriteOnce"
  # mountPath: ""         # custom-values에 없음 → 기본값 /home/jovyan 적용

dataVolume:
  enabled: false          # true로 설정 시 /home/jovyan/data에 PVC 마운트
  size: "5Gi"
  storageClassName: ""
  accessMode: "ReadWriteOnce"
  # mountPath: ""         # custom-values에 없음 → 기본값 "data" 적용
```

### groupVolumes

```yaml
groupVolumes: []
# 공유 PVC 마운트 예시:
# groupVolumes:
#   - claimName: "pvc-shared-data"
#     mountPath: "/group_data"
#   - claimName: "pvc-team-models"
#     mountPath: "/models"
```

## custom-values.yaml 미포함 필드 (values.yaml 기본값 적용)

| 필드 | 기본값 | 비고 |
|------|--------|------|
| `image.pullPolicy` | `IfNotPresent` | |
| `replicas` | `1` | 0으로 설정하면 Pod 중지 |
| `homeVolume.mountPath` | `""` → `/home/jovyan` | |
| `dataVolume.mountPath` | `""` → `data` | |
| `imagePullSecrets` | `[]` | Private 레지스트리 사용 시 추가 필요 |

## 배포 명령어

```bash
# 렌더링 미리보기 (실제 배포 없음)
helm template my-jupyter ./manifests/helm/jupyterlab/1.0.0 \
  -f ./manifests/helm/jupyterlab/1.0.0/custom-values.yaml

# 신규 설치
helm install my-jupyter ./manifests/helm/jupyterlab/1.0.0 \
  --namespace jupyter \
  --create-namespace \
  -f ./manifests/helm/jupyterlab/1.0.0/custom-values.yaml

# 업그레이드
helm upgrade my-jupyter ./manifests/helm/jupyterlab/1.0.0 \
  -n jupyter \
  -f ./manifests/helm/jupyterlab/1.0.0/custom-values.yaml

# 변경 사항 확인 (helm-diff 플러그인 필요)
helm diff upgrade my-jupyter ./manifests/helm/jupyterlab/1.0.0 \
  -n jupyter \
  -f ./manifests/helm/jupyterlab/1.0.0/custom-values.yaml
```

## 환경별 설정 예시

### 개발 환경 (최소 리소스, 인증 없음)

```yaml
image:
  repository: "jupyter/scipy-notebook"
  tag: "latest"

resources:
  limits:
    cpu: "500m"
    memory: "1024Mi"
  requests:
    cpu: "100m"
    memory: "256Mi"
  gpu: ""

jupyterConfig:
  token: ""

ingress:
  enabled: true
  ingressClassName: "kong"
  hosts:
    - host: "jupyter-dev.example.com"
      paths: [/]
  tls:
    - hosts: ["jupyter-dev.example.com"]
      secretName: "jupyter-dev-tls"
```

### 운영 환경 (토큰 인증, PVC, GPU)

```yaml
image:
  # repository에 태그 포함 방식 (권장 - 버전 고정)
  repository: "jupyter/scipy-notebook:2024-01-15"
  # 또는 분리 방식:
  # repository: "jupyter/scipy-notebook"
  # tag: "2024-01-15"

resources:
  limits:
    cpu: "4000m"
    memory: "8192Mi"
  requests:
    cpu: "1000m"
    memory: "2048Mi"
  gpu: "1"            # NVIDIA GPU 1개

jupyterConfig:
  token: "my-secure-token"

ingress:
  enabled: true
  ingressClassName: "kong"
  hosts:
    - host: "jupyter.example.com"
      paths: [/]
  tls:
    - hosts: ["jupyter.example.com"]
      secretName: "jupyter-prod-tls"

homeVolume:
  enabled: true
  size: "20Gi"
  storageClassName: "fast-ssd"
  accessMode: "ReadWriteOnce"

dataVolume:
  enabled: true
  size: "100Gi"
  storageClassName: "fast-ssd"
  accessMode: "ReadWriteOnce"

groupVolumes:
  - claimName: "pvc-shared-datasets"
    mountPath: "/datasets"
```