하이브리드 클라우드 환경 만들기

하이브리드 클라우드 환경 만들기 (hybrid-cloud-hybrid-cloud-setup)

이번에는 본인의 인프라 안에서 Qdrant 클러스터를 운영하는 방법을 알아볼게요. Qdrant Hybrid Cloud는 데이터 플레인이 고객의 Kubernetes 클러스터에 설치되고, 관리는 Qdrant Cloud Console에서 이뤄지는 방식이에요. 아래 지침을 따라 Hybrid Cloud Environment에 Qdrant 클러스터를 제대로 세팅해 봅시다.

Hybrid Cloud가 어떻게 동작하는지 먼저 알고 싶다면 개요 문서를 읽어 보세요.

출처: Qdrant 공식문서

사전 요구사항 (Prerequisites)

Qdrant Hybrid Cloud는 Enterprise 플랜의 일부로 제공돼요. 접근 권한을 받으려면 문의를 먼저 남겨 주세요.

Kubernetes 클러스터: Hybrid Cloud Environment를 만들려면 표준 규격(standard compliant) Kubernetes 클러스터가 필요해요. 이 클러스터는 어떤 클라우드(예: EKS), 온프레미스(예: vSphere), 또는 엣지 환경(예: vSphere)에서도 실행할 수 있어요. 자세한 내용은 배포 플랫폼을 참고하세요.
스토리지: 블록 스토리지를 제공하는 CSI(Container Storage Interface) 드라이버로 Kubernetes 클러스터를 구성해야 해요. 수직 확장(vertical scaling)을 위해서는 CSI 드라이버가 볼륨 확장(volume expansion) 을 지원해야 하고, StorageClass는 사전에 만들어져 있어야 해요. 백업과 복원을 위해서는 드라이버가 CSI 스냅샷과 복원을 지원해야 하며, VolumeSnapshotClass도 사전에 만들어야 해요. 자세한 내용은 배포 플랫폼을 참고하세요.
Kubernetes 노드: 만들 Qdrant 데이터베이스 클러스터를 위한 충분한 CPU와 메모리 용량이 필요해요. Hybrid Cloud 제어 플레인(control plane) 구성 요소에도 소량의 리소스가 필요하죠. Qdrant Hybrid Cloud는 x86_64와 ARM64 아키텍처를 지원해요.
권한: Qdrant Cloud Agent를 설치하려면 Kubernetes 클러스터에서 cluster-admin 접근 권한이 있어야 해요.
연결: 클러스터 안의 Qdrant Cloud Agent는 Qdrant Cloud에 연결할 수 있어야 해요. 포트 443에서 grpc.cloud.qdrant.io와 api.cloud.qdrant.io로 아웃바운드 연결을 만들 거예요.
위치: 기본적으로 Qdrant 서비스(예: Qdrant Cloud Agent, Operator, Cluster-Manager)는 registry.cloud.qdrant.io에서 Helm 차트와 컨테이너 이미지를 가져와요. Qdrant 데이터베이스 컨테이너 이미지는 docker.io에서 가져오죠. 전체 목록은 '이미지와 차트 미러링(Mirroring images and charts)'을 참고하세요.

참고: 이 이미지와 차트를 본인 레지스트리로 미러링해서 거기서 가져올 수도 있어요.

CLI 도구

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

kubectl
helm

kubectl과 helm이 연결하도록 구성된 Kubernetes 클러스터에 접근할 수 있어야 해요. 본인 Kubernetes 배포판의 문서를 참고하세요.

설치 (Installation)

Hybrid Cloud를 세팅하려면 Qdrant Cloud Console cloud.qdrant.io를 열고, 대시보드에서 Hybrid Cloud를 선택해요.
첫 Hybrid Cloud Environment를 만들기 전에 결제 정보를 제공하고 Hybrid Cloud 라이선스 계약에 동의해야 해요. 설치 마법사가 과정을 안내해 줄 거예요.

참고: Hybrid Cloud Environment 안에서 만든 Qdrant 클러스터에 대해서만 요금이 부과되고, 환경 자체에는 부과되지 않아요.

다음 항목을 지정해요:

Create Hybrid Cloud Environment

환경 이름 (Environment Name): Hybrid Cloud Environment의 이름
Kubernetes 네임스페이스 (Kubernetes Namespace): 서비스(예: agent, operator)를 위한 Kubernetes 네임스페이스. 네임스페이스를 선택하면 나중에 바꿀 수 없어요.

(선택) 다음 설정이 필요하면 구성해요:

operator, agent, cluster-manager, 모니터링 스택을 위한 노드 선택자(node selector)와 톨러레이션(toleration).
Hybrid Cloud 제어 플레인 구성 요소의 모든 Kubernetes 리소스에 추가될 제어 플레인 라벨.
인프라에서 Qdrant Cloud API로 연결할 때 프록시를 사용한다면 프록시 URL, 자격증명, 인증서를 지정할 수 있어요.
Qdrant 서비스(Agent, Operator, Cluster-manager, 모니터링 스택) 이미지용 컨테이너 레지스트리 URL. 기본값은 https://registry.cloud.qdrant.io/qdrant/예요.
Qdrant 서비스용 Helm 차트 저장소 URL. 기본값은 oci://registry.cloud.qdrant.io/qdrant-charts예요.
본인 컨테이너 레지스트리에 접근하기 위한 자격증명을 담은 선택적 시크릿(secret).

완료되면 Save and Generate Installation Command 버튼을 눌러 다음 단계로 진행해요 (아래 참고).

참고: Kubernetes 네임스페이스를 제외한 모든 설정은 나중에 변경할 수 있어요.

설치 명령 생성 (Generate Installation Command)

Save and Generate Installation Command를 클릭하면 Kubernetes 클러스터에서 실행해 Kubernetes operator와 agent의 초기 설치를 수행할 수 있는 스크립트가 생성돼요.

이 명령은 다음을 수행해요:

Kubernetes 네임스페이스가 없다면 생성해요.
Qdrant 컨테이너 레지스트리와 Qdrant Cloud API에 접근하기 위한 자격증명으로 필요한 시크릿을 설정해요.
registry.cloud.qdrant.io의 Helm 레지스트리에 로그인해요.
Qdrant cloud agent와 Kubernetes operator 차트를 설치해요.

이 명령은 초기 설치에만 필요해요. 이후에는 Qdrant Cloud Console을 사용해 agent와 operator를 업데이트할 수 있어요.

참고: 설치 명령을 두 번째로 생성하면 포함된 시크릿이 다시 생성되기 때문에, 시크릿을 갱신하려면 명령을 다시 적용해 줘야 해요.

고급 구성 (Advanced configuration)

이미지와 차트 미러링 (Mirroring images and charts)

필요한 아티팩트

컨테이너 이미지:

registry.cloud.qdrant.io/qdrant/qdrant
registry.cloud.qdrant.io/qdrant/qdrant-cloud-agent
registry.cloud.qdrant.io/qdrant/operator
registry.cloud.qdrant.io/qdrant/cluster-manager
registry.cloud.qdrant.io/qdrant/prometheus
registry.cloud.qdrant.io/qdrant/prometheus-config-reloader
registry.cloud.qdrant.io/qdrant/kube-state-metrics
registry.cloud.qdrant.io/qdrant/kubernetes-event-exporter
registry.cloud.qdrant.io/qdrant/qdrant-cluster-exporter

OCI(Open Containers Initiative) Helm 차트:

registry.cloud.qdrant.io/qdrant-charts/qdrant-cloud-agent
registry.cloud.qdrant.io/qdrant-charts/operator
registry.cloud.qdrant.io/qdrant-charts/qdrant-cluster-manager
registry.cloud.qdrant.io/qdrant-charts/prometheus
registry.cloud.qdrant.io/qdrant-charts/kubernetes-event-exporter
registry.cloud.qdrant.io/qdrant-charts/qdrant-cluster-exporter

필요한 모든 컨테이너 이미지와 Helm 차트를 본인 레지스트리로 미러링하려면, 레지스트리가 제공하는 자동 복제(replication) 기능을 사용해서 새 이미지 버전을 자동으로 받아오는 걸 권장해요. 또는 Skopeo 같은 도구로 이미지를 수동 동기화할 수도 있어요. 이미지를 수동으로 동기화할 때는 전체 또는 올바른 CPU 아키텍처로 동기화해야 한다는 점을 꼭 확인하세요.

자동 복제 (Automatic replication)

/qdrant/ 저장소 안의 컨테이너 이미지와 /qdrant-charts/ 저장소 안의 helm 차트가 모두 동기화되어 있는지 확인해요. 그런 다음 Hybrid Cloud Environment의 고급 섹션으로 가서 레지스트리 위치를 구성해요:

컨테이너 레지스트리 URL: your-registry.example.com/qdrant (예: your-registry.example.com/qdrant/qdrant-cloud-agent가 됨)
차트 저장소 URL: oci://your-registry.example.com/qdrant-charts (예: oci://your-registry.example.com/qdrant-charts/qdrant-cloud-agent가 됨)

레지스트리가 인증을 요구한다면, the-qdrant-namespace 네임스페이스에 인증 정보가 담긴 시크릿을 직접 만들어야 해요.

예:

kubectl --namespace the-qdrant-namespace create secret docker-registry my-creds \
  --docker-server='your-registry.example.com' \
  --docker-username='your-username' \
  --docker-password='your-password'

그런 다음 Hybrid Cloud Environment의 고급 섹션에서 이 시크릿을 참조하면 돼요.

수동 복제 (Manual replication)

이 예시는 Skopeo를 사용해요.

Qdrant Cloud 레지스트리에 대한 본인의 개인 자격증명은 온보딩 명령에서 찾거나, kubectl로 가져올 수 있어요:

kubectl get secrets qdrant-registry-creds --namespace the-qdrant-namespace \
  -o jsonpath='{.data.\.dockerconfigjson}' | base64 --decode | jq -r '.'

먼저 소스 레지스트리에 로그인해요:

skopeo login registry.cloud.qdrant.io

그리고 본인 레지스트리에 로그인해요:

skopeo login your-registry.example.com

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

skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant/operator your-registry.example.com/qdrant/operator
skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant/qdrant-cloud-agent your-registry.example.com/qdrant/qdrant-cloud-agent
skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant/prometheus your-registry.example.com/qdrant/prometheus
skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant/prometheus-config-reloader your-registry.example.com/qdrant/prometheus-config-reloader
skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant/kube-state-metrics your-registry.example.com/qdrant/kube-state-metrics
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/qdrant-cluster-exporter your-registry.example.com/qdrant/qdrant-cluster-exporter
skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant/kubernetes-event-exporter your-registry.example.com/qdrant/kubernetes-event-exporter

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

skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant-charts/prometheus your-registry.example.com/qdrant-charts/prometheus
skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant-charts/operator your-registry.example.com/qdrant-charts/operator
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
skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant-charts/qdrant-cloud-agent your-registry.example.com/qdrant-charts/qdrant-cloud-agent
skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant-charts/qdrant-cluster-exporter your-registry.example.com/qdrant-charts/qdrant-cluster-exporter
skopeo sync --all --src docker --dest docker registry.cloud.qdrant.io/qdrant-charts/kubernetes-event-exporter your-registry.example.com/qdrant-charts/kubernetes-event-exporter

위 구성으로 Hybrid Cloud Environment의 고급 섹션에 다음 값을 추가할 수 있어요:

컨테이너 레지스트리 URL: your-registry.example.com/qdrant
차트 저장소 URL: oci://your-registry.example.com/qdrant-charts

레지스트리가 인증을 요구한다면, 앞서 설명한 것과 같은 방식으로 시크릿을 만들고 참조하면 돼요.

시크릿 순환 (Rotating Secrets)

Qdrant 레지스트리에서 컨테이너 이미지와 차트를 가져오고 Qdrant Cloud API에 인증하는 데 사용하는 시크릿을 순환해야 한다면 다음 단계를 따라 해요:

Hybrid Cloud Environment 목록 또는 환경의 상세 페이지로 이동해요.
작업 메뉴에서 "Rotate Secrets" 를 선택해요.
작업을 확인해요.
Kubernetes 클러스터에서 실행해 시크릿을 갱신할 새 설치 명령을 받게 돼요.

설치 명령을 실행하지 않으면 시크릿이 갱신되지 않고, Hybrid Cloud Environment와 Qdrant Cloud API 사이의 통신이 동작하지 않게 돼요.

Rotate Hybrid Cloud Secrets

Hybrid Cloud Environment 삭제 (Deleting a Hybrid Cloud Environment)

Hybrid Cloud Environment를 삭제하려면 먼저 그 안의 모든 Qdrant 데이터베이스 클러스터를 삭제해야 해요. 그다음 환경 자체를 삭제할 수 있어요.

Hybrid Cloud Environment를 삭제한 뒤 Kubernetes 클러스터를 정리하려면, https://github.com/qdrant/qdrant-cloud-support-tools/tree/main/hybrid-cloud-cleanup에서 스크립트를 다운로드해 모든 Qdrant 관련 리소스를 제거할 수 있어요.

Kubernetes 클러스터에 연결된 상태에서 다음 명령을 실행해요. 스크립트는 kubectl과 helm이 설치되어 있어야 해요.

./hybrid-cloud-cleanup.sh your-qdrant-namespace

더 알아보기 (Learn more)

Hybrid Cloud 개요 — 하이브리드 클라우드 동작 방식
배포 플랫폼 — 지원되는 Kubernetes 플랫폼