Qdrant Private Cloud 설정

Qdrant Private Cloud 설정 (private-cloud-private-cloud-setup)

Qdrant Private Cloud를 설치하고 구성하는 방법을 단계별로 알아볼게요. 이 페이지에서는 요구 사항부터 설치, 구성, 업그레이드, 언인스톨까지 전 과정을 다룬답니다.

출처: Qdrant 공식문서 - Setup Private Cloud

요구 사항 (Requirements)

Kubernetes 클러스터: Qdrant Private Cloud를 설치하려면 표준 준수 Kubernetes 클러스터가 필요해요. 이 클러스터는 AWS EKS부터 VMWare vSphere까지 다양한 배포판으로, 어떤 클라우드, 온프레미스 또는 엣지 환경에서도 실행할 수 있어요. 자세한 내용은 Deployment Platforms를 참고하세요.
스토리지: 스토리지를 위해 Kubernetes 클러스터를 블록 스토리지를 제공하는 Container Storage Interface(CSI) 드라이버로 구성해야 해요. 수직 스케일링을 위해서는 CSI 드라이버가 볼륨 확장(volume expansion)을 지원해야 하고, 백업과 복원을 위해서는 CSI 스냅샷과 복원을 지원해야 해요.
- NFS 같은 네트워크 스토리지 시스템이나 S3 같은 오브젝트 스토리지 시스템은 지원되지 않아요.
권한: Qdrant Kubernetes Operator를 설치하려면 Kubernetes 클러스터에서 cluster-admin 접근 권한이 있어야 해요.
위치(Locations): 기본적으로 Qdrant Operator Helm 차트와 컨테이너 이미지는 registry.cloud.qdrant.io에서 제공돼요.

참고: 이 이미지와 차트를 여러분 자신의 레지스트리에 미러링해서 거기서 가져올 수도 있어요.

CLI 도구

온보딩 과정에서 Helm을 사용해 Qdrant Kubernetes Operator를 배포하게 돼요. 다음 도구가 설치되어 있는지 확인하세요:

kubectl
helm

kubectl과 helm이 클러스터에 연결하도록 구성된 상태로 Kubernetes 클러스터에 접근할 수 있어야 해요. 자세한 내용은 사용 중인 Kubernetes 배포판의 문서를 참고하세요.

필수 아티팩트 (Required artifacts)

컨테이너 이미지:

registry.cloud.qdrant.io/qdrant/qdrant
registry.cloud.qdrant.io/qdrant/operator
registry.cloud.qdrant.io/qdrant/cluster-manager
registry.cloud.qdrant.io/qdrant/qdrant-cluster-exporter

Open Containers Initiative(OCI) Helm 차트:

registry.cloud.qdrant.io/qdrant-charts/qdrant-private-cloud

registry.cloud.qdrant.io/library/qdrant-kubernetes-api

각 Private Cloud 버전의 구체적인 버전은 Private Cloud Changelog에 문서화되어 있어요.

설치 (Installation)

Qdrant Private Cloud에 온보딩되면 Qdrant Cloud Registry에 접근할 수 있는 자격 증명을 받게 돼요. 이 자격 증명을 사용해서 다음 명령으로 Qdrant Private Cloud 솔루션을 설치할 수 있어요:

Private Cloud 배포용 네임스페이스를 만드세요. 네임스페이스 이름은 아무거나 사용해도 되지만, 이후 단계들을 그에 맞게 수정해야 해요. 예:

kubectl create namespace qdrant-private-cloud

필요한 컨테이너 이미지를 Kubernetes 클러스터가 가져올 수 있도록, Qdrant Cloud Registry 자격 증명으로 Kubernetes 시크릿을 만드세요:

kubectl create secret docker-registry qdrant-registry-creds \
  --docker-server=registry.cloud.qdrant.io \
  --docker-username='your-username' \
  --docker-password='your-password' \
  --namespace qdrant-private-cloud

Helm으로 Qdrant Cloud Registry에 로그인하세요:

helm registry login 'registry.cloud.qdrant.io' --username 'your-username' --password 'your-password'

Qdrant Kubernetes Operator Custom Resource Definitions(CRD)를 설치하세요:

helm upgrade --install qdrant-private-cloud-crds \
  oci://registry.cloud.qdrant.io/qdrant-charts/qdrant-kubernetes-api \
  --namespace qdrant-private-cloud --version v1.37.7 --wait

Qdrant Private Cloud를 설치하세요:

helm upgrade --install qdrant-private-cloud \
  oci://registry.cloud.qdrant.io/qdrant-charts/qdrant-private-cloud \
  --namespace qdrant-private-cloud --version 1.9.15

설치하는 qdrant-private-cloud 버전과 호환되는 qdrant-kubernetes-api 버전을 사용하세요.

사용 가능한 버전 목록은 Private Cloud Changelog를 참고하세요.

현재 기본 버전은 다음과 같아요:

qdrant-kubernetes-api v1.37.7
qdrant-private-cloud 1.9.15

더 자세한 내용은 Helm 설치 문서(Helm Install Documentation)도 참고하세요.

Private Cloud 구성하기

Qdrant Private Cloud Helm 차트는 대부분의 배포에 적합한 기본값들을 포함하고 있어요. 하지만 특정 요구에 맞게 구성을 더 커스터마이즈할 수도 있어요. 사용 가능한 모든 구성 옵션은 Private Cloud Configuration 페이지에서 확인할 수 있어요.

Helm 값은 Operator와 관련 컴포넌트를 구성해요. 감사 로깅, 인증, TLS를 포함한 클러스터별 데이터베이스 설정은 QdrantCluster 리소스에 속해요. Operator를 설치한 뒤 Managing a Cluster를 참고하세요.

여러분의 환경에 맞게 기본 StorageClass와 해당 VolumeSnapshotClass가 적절히 설정되어 있는지 확인해야 해요.

자체 values.yaml 파일을 만들 때는, 실제로 변경하는 값만 넣는 것이 모범 사례예요. 예를 들어 이 values.yaml 파일처럼요:

operator:
  settings:
    features:
      clusterManagement:
        storageClass:
          database: your-storage-class-name
          snapshot: your-storage-class-name
      backupManagement:
        snapshots:
          volumeSnapshotClass: your-volume-snapshot-class-name

Qdrant Private Cloud를 이렇게 구성할 수 있어요:

helm upgrade --install qdrant-private-cloud \
  oci://registry.cloud.qdrant.io/qdrant-charts/qdrant-private-cloud \
  --namespace qdrant-private-cloud --version 1.9.15 -f values.yaml

업그레이드 (Upgrades)

Qdrant Private Cloud를 새 버전으로 업그레이드하려면, 먼저 Qdrant Kubernetes Operator Custom Resource Definitions(CRD)를 업그레이드하세요:

helm upgrade --install qdrant-private-cloud-crds \
  oci://registry.cloud.qdrant.io/qdrant-charts/qdrant-kubernetes-api \
  --namespace qdrant-private-cloud --version v1.37.7 --wait

그 다음, 같은 구성 값으로 Qdrant Private Cloud Helm 차트를 업그레이드하세요. 예:

helm upgrade --install qdrant-private-cloud \
  oci://registry.cloud.qdrant.io/qdrant-charts/qdrant-private-cloud \
  --namespace qdrant-private-cloud --version 1.9.15 -f values.yaml

이미지 태그 값은 차트의 appVersions에서 자동으로 파생되므로 values.yaml에서 재정의하면 안 된다는 점을 참고하세요.

더 자세한 내용은 Helm 업그레이드 문서(Helm Upgrade Documentation)도 참고하세요.

이미지와 차트 미러링하기

필요한 모든 컨테이너 이미지와 Helm 차트를 여러분 자신의 레지스트리로 미러링하려면, 레지스트리가 제공하는 복제(replication) 기능을 사용하거나, Skopeo로 이미지를 수동으로 동기화할 수 있어요:

먼저 원본 레지스트리에 로그인하세요:

skopeo login registry.cloud.qdrant.io

그 다음 여러분 자신의 레지스트리에 로그인하세요:

skopeo login your-registry.example.com

모든 컨테이너 이미지를 동기화하려면:

skopeo sync --all --src docker --dest docker \
  registry.cloud.qdrant.io/qdrant/qdrant your-registry.example.com/qdrant/qdrant

skopeo sync --all --src docker --dest docker \
  registry.cloud.qdrant.io/qdrant/cluster-manager your-registry.example.com/qdrant/cluster-manager

skopeo sync --all --src docker --dest docker \
  registry.cloud.qdrant.io/qdrant/operator your-registry.example.com/qdrant/operator

모든 Helm 차트를 동기화하려면:

skopeo sync --all --src docker --dest docker \
  registry.cloud.qdrant.io/qdrant-charts/qdrant-private-cloud your-registry.example.com/qdrant-charts/qdrant-private-cloud

skopeo sync --all --src docker --dest docker \
  registry.cloud.qdrant.io/qdrant-charts/qdrant-kubernetes-api your-registry.example.com/qdrant-charts/qdrant-kubernetes-api

설치나 업그레이드 중에는 Helm 차트 값에서 이미지 저장소와 imagePullSecret 정보를 맞게 조정해야 해요. 예:

operator:
  image:
    repository: your-registry.example.com/qdrant/operator
  imagePullSecrets:
    - name: your-registry-creds
  settings:
    features:
      clusterManagement:
        qdrant:
          image:
            repository: your-registry.example.com/qdrant/qdrant
            pullSecretName: your-registry-creds

qdrant-cluster-manager:
  image:
    repository: your-registry.example.com/qdrant/cluster-manager
  imagePullSecrets:
    - name: your-registry-creds

qdrant-cluster-exporter:
  image:
    repository: your-registry.example.com/qdrant/qdrant-cluster-exporter
  imagePullSecrets:
    - name: your-registry-creds

자세한 내용은 Private Cloud Configuration을 참고하세요.

Operator의 범위 (Scope of the operator)

기본적으로 Qdrant Operator는 자신이 배포된 것과 같은 Kubernetes 네임스페이스에 있는 Qdrant 클러스터만 관리해요. RoleBinding도 이 특정 네임스페이스로 제한돼요. 이 기본값은 Kubernetes 클러스터 내에서 Operator에 필요한 권한을 최소한으로 제한하도록 선택된 거예요.

같은 Operator로 여러 네임스페이스의 Qdrant 클러스터를 관리하고 싶다면, Operator가 감시(watch)할 네임스페이스 목록을 구성할 수 있어요:

operator:
  watch:
    # If true, watches only the namespace where the Qdrant operator is deployed, otherwise watches the namespaces in watch.namespaces
    onlyReleaseNamespace: false
    # an empty list watches all namespaces.
    namespaces:
      - qdrant-private-cloud
      - some-other-namespase
  limitRBAC: true

또는 Operator가 모든 네임스페이스를 감시하도록 구성할 수 있어요:

operator:
  watch:
    # If true, watches only the namespace where the Qdrant operator is deployed, otherwise watches the namespaces in watch.namespaces
    onlyReleaseNamespace: false
    # an empty list watches all namespaces.
    namespaces: []
  limitRBAC: false

언인스톨 (Uninstallation)

Qdrant Private Cloud 솔루션을 언인스톨하려면 다음 명령을 사용할 수 있어요:

helm uninstall qdrant-private-cloud --namespace qdrant-private-cloud
helm uninstall qdrant-private-cloud-crds --namespace qdrant-private-cloud
kubectl delete namespace qdrant-private-cloud

qdrant-private-cloud-crds Helm 차트를 언인스톨하면 모든 Custom Resource Definitions(CRD)가 제거되고, 그와 함께 Operator가 관리하던 모든 Qdrant 클러스터도 제거된다는 점을 참고하세요.

Qdrant Private Cloud 설정