Kubernetes 설치

Helm을 사용해 Kubernetes에 Pinot 클러스터를 배포하는 방법이에요. 스테이징이나 프로덕션 환경에서 Helm 차트를 이용해 프로덕션에 가까운 Pinot 클러스터를 손쉽게 띄울 수 있어요.

출처: Kubernetes

본문

이 페이지를 마치면 알게 되는 것 (Outcome)

Helm 차트로 Kubernetes에 프로덕션 준비가 된 Pinot 클러스터를 배포할 수 있어요.

⚠️ Helm 3 마이그레이션: Pinot Helm 차트가 Helm 3(apiVersion v2)으로 업그레이드됐어요. 이전 Helm 차트(v1)에서 업그레이드하는 경우 다음을 참고하세요:

최소 Helm 버전: Helm 3.0+ 필요

의존성 관리: helm dependency update가 아닌 helm dependency build 사용

의존성 파일: 차트가 이제 의존성 선언에 requirements.yaml이 아닌 Chart.yaml을 사용

락 파일: requirements.lock이 아닌 Chart.lock 사용

차트 아카이브: 더 이상 저장소에 체크인하지 않고 helm dependency build를 통해 자동으로 내려받음

차트 버전: 더 이상 -SNAPSHOT 접미사를 사용하지 않음

💡 이 가이드의 예제는 참조용 샘플 설정이에요. 프로덕션 배포에서는 특히 TLS와 인증 같은 보안 기능을 필요에 맞게 설정을 커스터마이즈하세요.

사전 요구 사항 (Prerequisites)

실행 중인 Kubernetes 클러스터. 옵션:
- Kubernetes가 활성화된 Docker Desktop
- Minikube -- 충분한 리소스로 시작: minikube start --vm=true --cpus=4 --memory=8g --disk-size=50g
- 관리형 클라우드 클러스터 -- AWS, GCP, Azure 설정 가이드는 Managed Kubernetes 참조
Helm 3 (apiVersion v2) -- Pinot Helm 차트에 필요. Helm 3 설치
kubectl

단계 (Steps)

1. Pinot Helm 저장소 추가

helm repo add pinot https://raw.githubusercontent.com/apache/pinot/master/helm

2. 네임스페이스 생성

kubectl create ns pinot-quickstart

3. Pinot 설치

사전 패키징된 차트로 Helm 설치:

helm install pinot pinot/pinot \
    -n pinot-quickstart \
    --set cluster.name=pinot \
    --set server.replicaCount=2

💡 StorageClass: 클라우드 벤더에 맞는 StorageClass를 지정하세요. 데이터 서빙 파일 시스템으로는 반드시 블록 스토리지만 사용하고 blob 저장소(S3, GCS, AzureFile)를 마운트하지 마세요.

AWS: gp2

GCP: pd-ssd 또는 standard

Azure: AzureDisk

Docker Desktop: hostpath

Git 저장소에서 Helm 설치:

git clone https://github.com/apache/pinot.git
cd pinot/helm/pinot
helm dependency build
kubectl create ns pinot-quickstart
helm install -n pinot-quickstart pinot ./pinot

💡 Helm 3 마이그레이션 (v2): Helm 3 apiVersion v2로의 이전 마이그레이션 이후, Pinot 차트는 의존성 선언에 requirements.yaml 대신 Chart.yaml, requirements.lock 대신 Chart.lock을 사용해요. helm dependency build 명령이 차트 저장소에서 의존성을 자동으로 내려받아요.

확인 (Verify)

배포 상태를 확인합니다:

kubectl get all -n pinot-quickstart

모든 파드가 Running 상태가 되어야 해요. Controller를 port-forward해 UI에 접근할 수 있어요:

kubectl port-forward service/pinot-controller 9000:9000 -n pinot-quickstart

그런 다음 http://localhost:9000을 엽니다.

데이터 로딩 (Loading data)

Kubernetes의 스트림 수집은 Kubernetes 스트림 수집 가이드를 참고하세요. 배치 데이터 로딩과 테이블 생성은 아래 온보딩 경로를 따라 계속 진행해요.

클러스터 삭제 (Deleting the cluster)

클러스터에서 Pinot를 제거하려면:

kubectl delete ns pinot-quickstart

다음 단계 (Next step)

클러스터가 실행 중이에요. 데이터를 로드하려면 첫 테이블과 스키마로 계속 진행하세요.

Helm v1 차트에서 업그레이드 (Upgrading from Helm v1 charts)

이전 Pinot Helm 차트(apiVersion v1)에서 업그레이드하는 경우 다음 단계를 따르세요:

1. Helm 저장소 업데이트

helm repo update pinot

2. 설정 백업

필요 시 참조할 수 있도록 현재 values.yaml을 저장하세요:

helm get values pinot -n pinot-quickstart > values-backup.yaml

3. 이전 릴리스 제거 (선택이지만 권장)

v1 차트에서 업그레이드하는 경우 제거 후 재설치하는 것이 가장 안전해요:

helm uninstall pinot -n pinot-quickstart

4. 새 Helm v2 차트로 재설치

helm install pinot pinot/pinot \
    -n pinot-quickstart \
    --set cluster.name=pinot \
    --set server.replicaCount=2 \
    -f values-backup.yaml

Helm v2 차트의 주요 변경 사항

apiVersion: v1에서 v2로 변경
차트 유형: 명시적 type: application 추가
의존성: requirements.yaml 대신 Chart.yaml에 선언
락 파일: requirements.lock에서 Chart.lock으로 변경
의존성 가져오기: helm dependency update 대신 helm dependency build 사용
차트 버전: 더 이상 -SNAPSHOT 접미사 포함하지 않음 (표준 SemVer 사용)
차트 아이콘: 공식 Apache Pinot 아이콘 포함

소스에서 배포할 때

Git 저장소에서 직접 배포할 때는 설치 전에 항상 helm dependency build를 실행하세요:

git clone https://github.com/apache/pinot.git
cd pinot/helm/pinot
helm dependency build  # Helm 3 v2 차트에 필요
helm install pinot . -n pinot-quickstart

Kubernetes 설치