You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
158 lines
5.3 KiB
158 lines
5.3 KiB
# Chart 개발 및 빌드 가이드
|
|
|
|
이 문서는 JupyterLab Helm chart의 구조와 템플릿 개발, 검증 방법을 설명합니다.
|
|
|
|
## 디렉토리 구조
|
|
|
|
```
|
|
jupyterlab/
|
|
├── Chart.yaml # 차트 메타데이터
|
|
├── values.yaml # 기본값 정의
|
|
├── custom-values.yaml # 환경별 override 예시
|
|
├── README.md # 사용자 가이드
|
|
├── CUSTOM-README.md # custom-values 작성 가이드
|
|
├── BUILD-README.md # 이 파일 (개발/빌드 가이드)
|
|
└── templates/
|
|
├── _helpers.tpl # 재사용 헬퍼 함수 정의
|
|
├── deployment.yaml # Deployment 리소스
|
|
├── service.yaml # Service 리소스
|
|
├── ingress.yaml # Ingress 리소스
|
|
├── pvc.yaml # PersistentVolumeClaim 리소스
|
|
└── configmap.yaml # ConfigMap (startup-script.sh)
|
|
```
|
|
|
|
## 템플릿 구조 설명
|
|
|
|
### `_helpers.tpl` — 헬퍼 함수
|
|
|
|
| 함수 | 반환값 예시 | 설명 |
|
|
|------|------------|------|
|
|
| `jupyterlab.name` | `my-jupyter` | 릴리즈 이름 그대로 사용 |
|
|
| `jupyterlab.configMapName` | `my-jupyter-scripts` | ConfigMap 이름 |
|
|
| `jupyterlab.homePvcName` | `pvc-my-jupyter-home` | 홈 PVC 이름 |
|
|
| `jupyterlab.dataPvcName` | `pvc-my-jupyter-data` | 데이터 PVC 이름 |
|
|
| `jupyterlab.homeDir` | `/home/jovyan` | `homeVolume.mountPath` 또는 기본값 |
|
|
| `jupyterlab.dataDir` | `/home/jovyan/data` | `<homeDir>/<dataVolume.mountPath>` |
|
|
| `jupyterlab.labels` | (라벨 맵) | 공통 라벨 세트 |
|
|
| `jupyterlab.image` | `quay.io/jupyter/scipy-notebook:latest` | 전체 이미지 참조. `repository`에 `:`가 있으면 `tag` 무시 |
|
|
| `jupyterlab.command` | (bash 커맨드 배열) | JupyterLab 시작 커맨드 |
|
|
|
|
### `deployment.yaml`
|
|
|
|
- `replicas`: `values.replicas`
|
|
- 보안 컨텍스트: Pod 레벨 `runAsUser: 1000 / fsGroup: 100`, Container 레벨 `runAsUser: 0`
|
|
- readinessProbe: `tcpSocket:8888`, 초기 30초 대기, 10초 주기, 27회 실패 허용 (총 ~5분)
|
|
- 볼륨: `localtime`, `startup-script`, `dshm` (항상), `home-volume`, `data-volume`, `groupVolumes` (조건부)
|
|
- `dshm`: RAM 기반 tmpfs를 `/dev/shm`에 마운트. PyTorch/NumPy 멀티프로세싱 시 기본 64MB 제한 해제
|
|
|
|
### `configmap.yaml`
|
|
|
|
startup-script.sh 내용:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
apt-get update -y
|
|
python -m pip install --upgrade pip
|
|
```
|
|
|
|
이 스크립트는 `/usr/local/bin/start-notebook.d/` 에 마운트되어 JupyterLab 시작 전 자동 실행됩니다.
|
|
추가 패키지 설치가 필요하면 이 파일을 수정하세요.
|
|
|
|
### `pvc.yaml`
|
|
|
|
- `homeVolume.enabled: true` 일 때만 `pvc-<release>-home` 생성
|
|
- `dataVolume.enabled: true` 일 때만 `pvc-<release>-data` 생성
|
|
- `storageClassName`이 비어 있으면 클러스터 기본 StorageClass 사용
|
|
- PVC 보존 필요 시 주석 해제: `helm.sh/resource-policy: keep`
|
|
|
|
### `ingress.yaml`
|
|
|
|
- `ingress.enabled: false` 이면 리소스 생성 안 함
|
|
- annotations는 `range`로 동적 주입 (Kong, cert-manager 설정 포함)
|
|
- pathType은 `Prefix`로 고정
|
|
|
|
## 개발 시 자주 쓰는 명령어
|
|
|
|
### 렌더링 검증
|
|
|
|
```bash
|
|
# 전체 렌더링 출력
|
|
helm template my-jupyter . -f custom-values.yaml
|
|
|
|
# 특정 리소스만 확인
|
|
helm template my-jupyter . -f custom-values.yaml | \
|
|
kubectl neat | grep -A50 "kind: Deployment"
|
|
|
|
# values 병합 결과 확인
|
|
helm template my-jupyter . -f custom-values.yaml --debug 2>&1 | head -50
|
|
```
|
|
|
|
### Lint
|
|
|
|
```bash
|
|
helm lint . -f custom-values.yaml
|
|
```
|
|
|
|
### values 스키마 검증 (schema 파일 추가 시)
|
|
|
|
```bash
|
|
helm template my-jupyter . -f custom-values.yaml --validate
|
|
```
|
|
|
|
### 실 클러스터 dry-run
|
|
|
|
```bash
|
|
helm install my-jupyter . \
|
|
--namespace jupyter \
|
|
--create-namespace \
|
|
-f custom-values.yaml \
|
|
--dry-run
|
|
```
|
|
|
|
## 새 기능 추가 시 체크리스트
|
|
|
|
- [ ] `values.yaml`에 새 키와 기본값 추가
|
|
- [ ] `_helpers.tpl`에 필요한 헬퍼 함수 추가
|
|
- [ ] 해당 템플릿 파일에 조건부 블록으로 구현 (`{{- if .Values.xxx }}`)
|
|
- [ ] `custom-values.yaml`에 예시값 반영
|
|
- [ ] `helm lint` 통과 확인
|
|
- [ ] `helm template` 렌더링 결과 확인
|
|
- [ ] `README.md` Values 테이블 업데이트
|
|
|
|
## 자주 발생하는 오류
|
|
|
|
### Error: YAML parse error
|
|
|
|
`values.yaml`이나 `custom-values.yaml`의 들여쓰기 오류.
|
|
`helm lint` 로 위치 확인.
|
|
|
|
### Error: template: jupyterlab/templates/xxx.yaml: ... nil pointer evaluating
|
|
|
|
`values.yaml`에 존재하지 않는 키를 템플릿에서 참조할 때 발생.
|
|
`_helpers.tpl`에서 `default` 함수 사용:
|
|
|
|
```
|
|
{{ .Values.some.key | default "fallback" }}
|
|
```
|
|
|
|
### PVC Pending 상태
|
|
|
|
`storageClassName`이 클러스터에 없는 경우.
|
|
`kubectl get storageclass` 로 사용 가능한 클래스 확인 후 설정.
|
|
|
|
### Pod CrashLoopBackOff
|
|
|
|
startup-script.sh 오류 가능성 높음.
|
|
`kubectl logs <pod> -n <namespace>` 로 스크립트 실행 로그 확인.
|
|
|
|
## Chart 버전 관리
|
|
|
|
`Chart.yaml`의 `version` 필드는 **SemVer** 규칙을 따릅니다.
|
|
|
|
| 변경 유형 | 버전 업 | 예시 |
|
|
|----------|---------|------|
|
|
| 하위 호환 버그 픽스 | patch | `1.0.0` → `1.0.1` |
|
|
| 새 기능 추가 (하위 호환) | minor | `1.0.0` → `1.1.0` |
|
|
| 하위 비호환 변경 | major | `1.0.0` → `2.0.0` |
|
|
|
|
`appVersion`은 JupyterLab 애플리케이션 버전을 나타내며, chart version과 별도로 관리합니다.
|
|
|