Kubernetes 설치

Kubernetes 설치 (Kubernetes Installation)

Docker가 단일 머신에 Weaviate를 올리는 빠른 경로라면, Kubernetes(쿠버네티스)는 운영 환경에서 확장·복제를 염두에 둔 설치 방식이에요. Helm 차트를 쓰면 영구 볼륨, gRPC 서비스, 인증 설정까지 코드로 관리할 수 있습니다. 다만 사전 요건이 조금 있고, 버전 설정 같은 디테일이 실제 운영에서 중요해요.

출처: 공식문서 — Kubernetes

사전 요건

최근 Kubernetes 클러스터(최소 1.23 이상). 개발 환경이라면 Docker Desktop에 내장된 클러스터를 고려할 수 있어요.
클러스터가 PersistentVolumeClaims로 PersistentVolumes를 프로비저닝할 수 있어야 함.
단일 노드가 읽기-쓰기로 마운트할 수 있어 Kubernetes ReadWriteOnce 접근 모드를 지원하는 파일 시스템.
Helm v3 이상. 현재 차트 버전은 17.8.3.

참고로 Weaviate는 기본적으로 텔레메트리를 수집합니다. 끄는 방법은 텔레메트리 페이지에서 다뤄요.

중요: Helm 차트에 Weaviate 버전을 명시하는 걸 모범 사례로 권장합니다. values.yaml에 버전을 적거나 배포 시 기본값을 덮어쓰세요.

Helm 설치 절차

먼저 Helm과 kubectl이 제대로 설정됐는지 확인합니다.

# helm이 설치됐는지 확인
helm version
# kubectl이 올바르게 설정되어 클러스터에 접근 가능한지 확인.
# 예를 들어 현재 네임스페이스의 파드를 나열해 본다.
kubectl get pods

Weaviate Helm 저장소를 추가합니다.

helm repo add weaviate https://weaviate.github.io/weaviate-helm
helm repo update

기본 values.yaml을 가져옵니다.

helm show values weaviate/weaviate > values.yaml

환경에 맞게 values.yaml을 편집합니다. 기본 파일은 상세히 주석이 달려 있어 구성하기 좋아요. 기본 설정은 하나의 Weaviate 레플리카 클러스터를 정의합니다.

로컬 모델(text2vec-transformers, qna-transformers, img2vec-neural)은 기본적으로 비활성화되어 있어요. 모델을 쓰려면 해당 모델의 enabled 플래그를 true로 설정하면 됩니다.

Helm 차트 17.0.1부터 모듈 리소스 제약이 주석 처리되어 성능이 개선돼요. 특정 모듈에 리소스를 제한하고 싶으면 values.yaml에 제약을 추가하면 됩니다.
Helm 차트 17.0.0부터 gRPC 서비스가 기본으로 활성화됩니다. 더 오래된 차트를 쓴다면 values.yaml을 편집해 gRPC를 켜야 해요.

외부에서 gRPC API에 접근하려면 enabled가 true, type이 LoadBalancer인지 확인합니다.

grpcService:
  enabled: true  # ⬅️ true로 설정해야 함
  name: weaviate-grpc
  ports:
  - name: grpc
    protocol: TCP
    port: 50051
  type: LoadBalancer  # ⬅️ NodePort에서 LoadBalancer로 설정

tip: Helm 차트는 Weaviate를 배포할 때마다 임의의 사용자 이름/비밀번호를 자동 생성해요. 그래서 Helm으로 배포하면 노드 간 통신이 항상 보안됩니다.

인증 구성 예시:

authentication:
  apikey:
    enabled: true
    allowed_keys:
    - readonly-key
    - secr3tk3y
    users:
    - [email protected]
    - [email protected]
  anonymous_access:
    enabled: false
  oidc:
    enabled: true
    issuer: https://auth.wcs.api.weaviate.io/auth/realms/SeMI
    username_claim: email
    groups_claim: groups
    client_id: wcs
authorization:
  admin_list:
    enabled: true
    users:
    - [email protected]
    - [email protected]
    readonly_users:
    - [email protected]

이 예시에서 readonly-key는 [email protected]으로, secr3tk3y는 [email protected]으로 인증돼요. OIDC도 활성화돼 있고, WCD가 토큰 발급자·ID 제공자 역할을 합니다. [email protected]는 admin으로 설정돼서 인증 시 읽기·쓰기 전체 권한을 받아요.

경고: OIDC로 Weaviate Cloud(WCD)에 연결하는 방식은 더 이상 사용되지 않습니다(디프리케이트). API 키 인증을 쓰세요.

기본적으로 weaviate는 root 사용자로 실행됩니다. 비권한 사용자로 실행하려면 containerSecurityContext 섹션에서 설정을 바꾸면 돼요. init 컨테이너는 노드를 구성하기 때문에 항상 root로 실행되고, 시스템이 시작된 뒤에는 설정한 비권한 사용자로 실행됩니다.

Helm 차트를 배포합니다.

# Weaviate 네임스페이스 생성
kubectl create namespace weaviate
# 배포
helm upgrade --install \
  "weaviate" \
  weaviate/weaviate \
  --namespace "weaviate" \
  --values ./values.yaml

위 명령은 새 네임스페이스를 만들 권한이 있다고 가정해요. 네임스페이스 레벨 권한만 있다면 새 네임스페이스 생성은 건너뛰고, 미리 준비된 네임스페이스 이름으로 helm upgrade의 네임스페이스 인자를 조정하면 됩니다. --create-namespace 파라미터를 주면 네임스페이스가 없을 때 만들어 줍니다. helm upgrade 명령은 멱등적이라 원하는 구성으로 조정해도 여러 번 실행해도 무방해요.

중요: v1.25 이상으로 업그레이드하려면 먼저 배포된 StatefulSet을 삭제하고, Helm 차트를 17.0.0 이상으로 업데이트한 뒤 Weaviate를 다시 배포해야 해요. 자세한 내용은 1.25 마이그레이션 가이드를 참고하세요.

스토리지 주의사항

일부 상황에서는 Weaviate에 EFS(Amazon Elastic File System)를 쓰고 싶을 수 있어요. AWS Fargate의 경우 PVC가 PV를 만들지 않으므로 PV(영구 볼륨)를 직접 만들어야 합니다. EFS를 쓰려면:

EFS 파일 시스템 생성
Weaviate 레플리카마다 EFS access point 생성 — 모든 Access Point의 루트 디렉터리가 서로 달라야 함(그래야 파드가 데이터를 공유하지 않음, 아니면 실패)
Weaviate가 배포된 VPC의 각 서브넷에 EFS mount target 생성
Kubernetes에서 EFS를 쓰는 StorageClass 생성
각 볼륨이 서로 다른 AccessPoint를 VolumeHandle로 갖도록 Weaviate Volume 생성
Weaviate 배포

weaviate-0 파드용 PV 예시:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: weaviate-0
spec:
  capacity:
    storage: 8Gi
  volumeMode: Filesystem
  accessModes:
  - ReadWriteOnce
  persistentVolumeReclaimPolicy: Delete
  storageClassName: "efs-sc"
  csi:
    driver: efs.csi.aws.com
    volumeHandle: <FileSystemId>::<AccessPointId-for-weaviate-0-Pod>
  claimRef:
    namespace: <namespace where Weaviate is/going to be deployed>
    name: weaviate-data-weaviate-0

Azure에서는 provisioner file.csi.azure.com를 지원하지 않아 파일 손상이 생길 수 있어요. values.yaml의 storage class가 disk.csi.azure.com 프로비저너를 쓰는지 확인하세요. 예:

storage:
  size: 32Gi
  storageClassName: managed

클러스터에서 사용 가능한 storage class 목록은 kubectl get storageclasses로 확인합니다.

No private IP address found, and explicit IP not provided 오류가 보이면 파드 서브넷을 다음 유효 IP 범위로 설정하세요.

10.0.0.0/8
100.64.0.0/10
172.16.0.0/12
192.168.0.0/16
198.19.0.0/16

클러스터 호스트명이 시간에 따라 바뀔 수 있는 시스템에서는 단일 노드 배포에 문제가 생길 수 있어요. values.yaml에 CLUSTER_HOSTNAME을 설정해 두면 됩니다.

env:
  CLUSTER_HOSTNAME: "node-1"

Kubernetes 설치