jupyterlab

2026-03-26 15:14:05 +09:00
parent d3d3ee8496
commit af34d9280e
12 changed files with 936 additions and 0 deletions
@@ -0,0 +1,215 @@
+# 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 사용
+  repository: "jupyter/scipy-notebook"
+  tag: "latest"              # 특정 버전 고정 권장 (예: "2024-01-15")
+```
+
+> `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 \
+  -f ./manifests/helm/jupyterlab/custom-values.yaml
+
+# 신규 설치
+helm install my-jupyter ./manifests/helm/jupyterlab \
+  --namespace jupyter \
+  --create-namespace \
+  -f ./manifests/helm/jupyterlab/custom-values.yaml
+
+# 업그레이드
+helm upgrade my-jupyter ./manifests/helm/jupyterlab \
+  -n jupyter \
+  -f ./manifests/helm/jupyterlab/custom-values.yaml
+
+# 변경 사항 확인 (helm-diff 플러그인 필요)
+helm diff upgrade my-jupyter ./manifests/helm/jupyterlab \
+  -n jupyter \
+  -f ./manifests/helm/jupyterlab/custom-values.yaml
+```
+
+## 환경별 설정 예시
+
+### 개발 환경 (최소 리소스, 인증 없음)
+
+```yaml
+image:
+  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:
+  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"
+```