Set up your environment

To set up your environment with Cloud Shell, follow these steps:

1. Set environment variables for your project, region, and a Kubernetescluster resource prefix:

   For the purpose of this tutorial, useus-central1 region to create your deploymentresources.

   exportPROJECT_ID=PROJECT_IDexportKUBERNETES_CLUSTER_PREFIX=qdrantexportREGION=us-central1

   • ReplacePROJECT_ID with your Google Cloudproject ID.

2. Check the version of Helm:

   helmversion

   Update the version if it's older than 3.13:

   curlhttps://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3|bash

3. Clone the sample code repository from GitHub:

   gitclonehttps://github.com/GoogleCloudPlatform/kubernetes-engine-samples

4. Navigate to theqdrant directory to start creating deployment resources:

   cdkubernetes-engine-samples/databases/qdrant

Create your cluster infrastructure

This section involves running a Terraform script to create a private, highly-available,regional GKE cluster to deploy your Qdrant database.

You can choose to deploy Qdrant using aStandard or Autopilot cluster. Each has its own advantagesand different pricing models.

exportGOOGLE_OAUTH_ACCESS_TOKEN=$(gcloudauthprint-access-token)terraform-chdir=terraform/gke-autopilotinitterraform-chdir=terraform/gke-autopilotapply\-varproject_id=${PROJECT_ID}\-varregion=${REGION}\-varcluster_prefix=${KUBERNETES_CLUSTER_PREFIX}

...Apply complete! Resources: 9 added, 0 changed, 0 destroyed.Outputs:kubectl_connection_command = "gcloud container clusters get-credentials qdrant-cluster --region us-central1"

exportGOOGLE_OAUTH_ACCESS_TOKEN=$(gcloudauthprint-access-token)terraform-chdir=terraform/gke-standardinitterraform-chdir=terraform/gke-standardapply\-varproject_id=${PROJECT_ID}\-varregion=${REGION}\-varcluster_prefix=${KUBERNETES_CLUSTER_PREFIX}

...Apply complete! Resources: 10 added, 0 changed, 0 destroyed.Outputs:kubectl_connection_command = "gcloud container clusters get-credentials qdrant-cluster --region us-central1"

Connect to the cluster

Configurekubectl to fetch credentials and communicate with your new GKE cluster:

gcloudcontainerclustersget-credentials\${KUBERNETES_CLUSTER_PREFIX}-cluster--location${REGION}

Deploy the Qdrant database to your cluster

In this tutorial, you deploy the Qdrant database (indistributed mode)and the Stateful HA operator to your GKE cluster clusterusing theHelm chart.

The deployment creates a GKE cluster with the following configuration:

• Three replicas of the Qdrant nodes.
• Tolerations, node affinities, and topology spread constraints are configuredto ensure proper distribution across Kubernetes nodes. This leverages the nodepools and different availability zones.
• A RePD volume with the SSD disk type is provisioned for data storage.
• A Stateful HA operator is used to manage failover processes and ensurehigh availability. A StatefulSet is a Kubernetes controller that maintains a persistent unique identity for each of its Pods.
• For authentication, the database creates a Kubernetes secret containing the API key.

To use the Helm chart to deploy Qdrant database, follow these steps:

1. Enable theStatefulHA add-on:

   Autopilot

   GKE automatically enablestheStatefulHA add-on at cluster creation.

   Standard

   Run the following command:

   gcloudcontainerclustersupdate${KUBERNETES_CLUSTER_PREFIX}-cluster\--project=${PROJECT_ID}\--location=${REGION}\--update-addons=StatefulHA=ENABLED

   It might take 15 minutes for this command to complete and for the clusterto show a ready status.

2. Add the Qdrant database Helm Chart repository before you can deploy it on yourGKE cluster:

   helmrepoaddqdranthttps://qdrant.github.io/qdrant-helm

3. Create namespaceqdrant for the database:

   kubectlcreatensqdrant

4. Apply the manifest to create a regional persistent SSD diskStorageClass:

   kubectlapply-nqdrant-fmanifests/01-regional-pd/regional-pd.yaml

   Theregional-pd.yaml manifest describes the persistent SSD diskStorageClass:

   apiVersion:storage.k8s.io/v1kind:StorageClassallowVolumeExpansion:truemetadata:name:ha-regionalparameters:replication-type:regional-pdtype:pd-ssdavailability-class:regional-hard-failoverprovisioner:pd.csi.storage.gke.ioreclaimPolicy:RetainvolumeBindingMode:WaitForFirstConsumer

5. Deploy a Kubernetes configmap with ametrics sidecar configuration and a Qdrantcluster by using Helm:

   kubectlapply-nqdrant-fmanifests/03-prometheus-metrics/metrics-cm.yamlhelminstallqdrant-databaseqdrant/qdrant-nqdrant\-fmanifests/02-values-file/values.yaml

   Themetrics-cm.yaml manifest describes themetrics sidecarConfigMap:

   apiVersion:v1kind:ConfigMapmetadata:name:nginx-confdata:default.conf.template:|server {listen 80;location / {proxy_pass http://localhost:6333/metrics;proxy_http_version 1.1;proxy_set_header Host $http_host;proxy_set_header api-key ${QDRANT_APIKEY};proxy_set_header X-Forwarded-For $remote_addr;}}

   Thevalues.yaml manifest describes the Qdrant cluster configuration :

   replicaCount:3config:service:enable_tls:falsecluster:enabled:truestorage:optimizers:deleted_threshold:0.5vacuum_min_vector_number:1500default_segment_number:2max_segment_size_kb:nullmemmap_threshold_kb:nullindexing_threshold_kb:25000flush_interval_sec:5max_optimization_threads:1livenessProbe:enabled:trueinitialDelaySeconds:60resources:limits:cpu:"2"memory:4Girequests:cpu:"1"memory:4Gitolerations:-key:"app.stateful/component"operator:"Equal"value:"qdrant"effect:NoScheduleaffinity:nodeAffinity:preferredDuringSchedulingIgnoredDuringExecution:-weight:1preference:matchExpressions:-key:"app.stateful/component"operator:Invalues:-"qdrant"topologySpreadConstraints:-maxSkew:1topologyKey:"topology.kubernetes.io/zone"whenUnsatisfiable:ScheduleAnywaylabelSelector:matchLabels:app.kubernetes.io/name:qdrantapp.kubernetes.io/instance:qdrantpodDisruptionBudget:enabled:truemaxUnavailable:1persistence:accessModes:["ReadWriteOnce"]size:10GistorageClassName:ha-regionalapiKey:truesidecarContainers:-name:metricsimage:nginx:1.29resources:requests:memory:"128Mi"cpu:"250m"limits:memory:"128Mi"cpu:"500m"ports:-containerPort:80env:-name:QDRANT_APIKEYvalueFrom:secretKeyRef:name:qdrant-database-apikeykey:api-keyvolumeMounts:-name:nginx-confmountPath:/etc/nginx/templates/default.conf.templatesubPath:default.conf.templatereadOnly:trueadditionalVolumes:-name:nginx-confconfigMap:name:nginx-confitems:-key:default.conf.templatepath:default.conf.template

   This configuration enables the cluster mode, allowing you to setup a highlyavailable and distributed Qdrant cluster.

6. Add a label to Qdrant statefulset:

   kubectllabelstatefulsetqdrant-databaseexamples.ai.gke.io/source=qdrant-guide-nqdrant

7. Deploy an internal load balancer to access your Qdrant database that's runningin the same VPC as your GKE cluster:

   kubectlapply-nqdrant-fmanifests/02-values-file/ilb.yaml

   Theilb.yaml manifest describes theLoadBalancer Service:

   apiVersion:v1kind:Servicemetadata:annotations:#cloud.google.com/neg: '{"ingress": true}'networking.gke.io/load-balancer-type:"Internal"labels:app.kubernetes.io/name:qdrantname:qdrant-ilbspec:ports:-name:httpport:6333protocol:TCPtargetPort:6333-name:grpcport:6334protocol:TCPtargetPort:6334selector:app:qdrantapp.kubernetes.io/instance:qdrant-databasetype:LoadBalancer

8. Check the deployment status:

   helmls-nqdrant

   The output is similar to the following, if theqdrant database is successfully deployed:

   NAME    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSIONqdrant-database  qdrant          1               2024-02-06 20:21:15.737307567 +0000 UTC deployed        qdrant-0.7.6    v1.7.4

9. Wait for GKE to start the required workloads:

   kubectlwaitpods-lapp.kubernetes.io/instance=qdrant-database--forcondition=Ready--timeout=300s-nqdrant

   This command might take a few minutes to complete successfully.

10. Once GKE starts the workloads, verify that GKE has createdthe Qdrant workloads:

    kubectlgetpod,svc,statefulset,pdb,secret-nqdrant

11. Start theHighAvailabilityApplication (HAA) resource for Qdrant:

    kubectlapply-nqdrant-fmanifests/01-regional-pd/ha-app.yaml

    Theha-app.yaml manifest describes theHighAvailabilityApplication resource:

    kind:HighAvailabilityApplicationapiVersion:ha.gke.io/v1metadata:name:qdrant-databasenamespace:qdrantspec:resourceSelection:resourceKind:StatefulSetpolicy:storageSettings:requireRegionalStorage:truefailoverSettings:forceDeleteStrategy:AfterNodeUnreachableafterNodeUnreachable:afterNodeUnreachableSeconds:20# 60 seconds total

    The following GKE resources are created for the Qdrant cluster:

    • The QdrantStatefulSet that controls three Pod replicas.
    • A PodDisruptionBudget, ensuring a maximum of one unavailable replica.
    • Theqdrant-database Service, exposing the Qdrant port for inbound connectionsand replication between nodes.
    • Theqdrant-database-headless Service, providing the list of running QdrantPods.
    • Theqdrant-database-apikey Secret, facilitating secure database connection.
    • Stateful HA operator Pod andHighlyAvailableApplication resource, actively monitoring the Qdrantapplication. TheHighlyAvailableApplication resource defines failover rules to apply against Qdrant.

12. To check if the failover rules are applied, describe the resource and confirmStatus: Message: Application is protected.

    kubectldescribehighavailabilityapplicationqdrant-database-nqdrant

    The output is similar to the following:

    Status:Conditions:    Last Transition Time:  2023-11-30T09:54:52Z    Message:               Application is protected    Observed Generation:   1    Reason:                ApplicationProtected    Status:                True    Type:                  Protected

Run queries with Vertex AI Colab Enterprise notebook

Qdrant organizes vectors and payloads in collections. Vector embedding is a techniquethat represents words or entities as numerical vectors while maintaining theirsemantic relationships. This is important for similarity searches as it enablesfinding similarities based on meaning rather than exact matches, making tasks likesearch and recommendation systems more effective and nuanced.

This section shows you how toupload Vectorsinto a new QdrantCollectionand run a search queries.

In this example, you use a dataset from a CSV file that contains a list of booksin different genres. You create a Colab Enterprise notebook to performa search query on the Qdrant database.

For more information about Vertex AI Colab Enterprise, seeColab Enterprise documentation.

Create a runtime template

To create a Colab Enterprise runtime template:

1. In the Google Cloud console, go to the Colab EnterpriseRuntime Templatespage and make sure your project is selected:

   Go to Runtime Templates

2. Clickadd_boxNew Template. TheCreate new runtime template page appears.

3. In theRuntime basics section:

   • In theDisplay name field, enterqdrant-connect.
   • In theRegion drop-down list, selectus-central1. It's the same region as your GKE cluster.

4. In theConfigure compute section:

   • In theMachine type drop-down list, selecte2-standard-2.
   • In theDisk size field, enter30.

5. In theNetworking and security section:

   • In theNetwork drop-down list, select the network where yourGKE cluster resides.
   • In theSubnetwork drop-down list, select a corresponding subnetwork.
   • Clear theEnable public internet access checkbox.

6. To finish creating the runtime template, clickCreate. Your runtime templateappears in the list on theRuntime templates tab.

Create a runtime

To create a Colab Enterprise runtime:

1. In the runtime templates list for the template you just created, in theActions column,clickmore_vert and thenclickCreate runtime. TheCreate Vertex AI Runtime pane appears.

2. To create a runtime based on your template, clickCreate.

3. On theRuntimes tab that opens, wait for the status to transition toHealthy.

Import the notebook

To import the notebook in Colab Enterprise:

1. Go to theMy Notebooks tab and clickImport. TheImport notebookspane appears.

2. InImport source, selectURL.

3. UnderNotebook URLs, enter the following link:

   https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes-engine-samples/refs/heads/main/databases/qdrant/manifests/04-notebook/vector-database.ipynb

4. ClickImport.

Connect to the runtime and run queries

To connect to the runtime and run queries:

1. In the notebook, next to theConnect button, clickarrow_drop_downAdditional connection options.TheConnect to Vertex AI Runtime pane appears.

2. SelectConnect to a runtime and then selectConnect to an existing Runtime.

3. Select the runtime that you launched and clickConnect.

4. To run the notebook cells, click theRun cell button next to each code cell.

The notebook contains both code cells and text that describes each code block. Runninga code cell executes its commands and displays an output. You can run the cellsin order, or run individual cells as needed.

View Prometheus metrics for your cluster

The GKE cluster is configured withGoogle Cloud Managed Service for Prometheus, which enablescollection of metrics in the Prometheus format. This service provides a fullymanaged solution for monitoring and alerting, allowing for collection, storage,and analysis of metrics from the cluster and its applications.

The following diagram shows how Prometheus collects metrics for your cluster:

The GKE private cluster in the diagram contains the following components:

• Qdrant Pods that expose metrics on the path/ and port80. These metricsare provided by the sidecar container namedmetrics.
• Prometheus-based collectors that process the metrics from the Qdrant Pods.
• A PodMonitoring resource that sends the metrics to Cloud Monitoring.

To export and view the metrics, follow these steps:

1. Create thePodMonitoringresource to scrape metrics bylabelSelector:

   kubectlapply-nqdrant-fmanifests/03-prometheus-metrics/pod-monitoring.yaml

   Thepod-monitoring.yaml manifest describes thePodMonitoring resource:

   apiVersion:monitoring.googleapis.com/v1kind:PodMonitoringmetadata:name:qdrantspec:selector:matchLabels:app:qdrantapp.kubernetes.io/instance:qdrant-databaseendpoints:-port:80interval:30spath:/

2. Create a Cloud Monitoring dashboardwith the configurations defined indashboard.json :

   gcloud--project"${PROJECT_ID}"monitoringdashboardscreate--config-from-filemonitoring/dashboard.json

3. After the command runs successfully, go to the Cloud MonitoringDashboards:

   Go to Dashboards overview

4. From the list of dashboards, open theQdrant Overview dashboard. It mighttake 1-2 minutes to collect and display metrics.

   The dashboard shows a count of key metrics:

   • Collections
   • Embedded vectors
   • Pending operations
   • Running nodes

Back up your cluster configuration

TheBackup for GKEfeature lets you schedule regular backups of your entire GKE clusterconfiguration, including the deployed workloads and their data.

In this tutorial, you configure a backup plan for your GKE cluster to performbackups of all workloads, including Secrets and Volumes, every day at 3 AM.To ensure efficient storage management, backups older than three days would be automatically deleted.

To configureBackup plans,follow these steps:

1. Enable the Backup for GKE feature for your cluster:

   gcloudcontainerclustersupdate${KUBERNETES_CLUSTER_PREFIX}-cluster\--project=${PROJECT_ID}\--location=${REGION}\--update-addons=BackupRestore=ENABLED

2. Create a backup plan with a daily schedule for all namespaces within the cluster:

   gcloudbetacontainerbackup-restorebackup-planscreate${KUBERNETES_CLUSTER_PREFIX}-cluster-backup\--project=${PROJECT_ID}\--location=${REGION}\--cluster="projects/${PROJECT_ID}/locations/${REGION}/clusters/${KUBERNETES_CLUSTER_PREFIX}-cluster"\--all-namespaces\--include-secrets\--include-volume-data\--cron-schedule="0 3 * * *"\--backup-retain-days=3

   The command uses the relevant environment variables at runtime.

   The cluster name's format is relative to your project and region as follows:

   projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME

   When prompted, typey.The output is similar to the following:

   Create request issued for: [qdrant-cluster-backup]Waiting for operation [projects/PROJECT_ID/locations/us-central1/operations/operation-1706528750815-610142ffdc9ac-71be4a05-f61c99fc] to complete...⠹

   This operation might take a few minutes to complete successfully. After theexecution is complete, the output is similar to the following:

   Created backup plan [qdrant-cluster-backup].

3. You can see your newly created backup planqdrant-cluster-backup listed onthe Backup for GKE console.

   Go to Backup for GKE

If you want to restore the saved backup configurations, seeRestore a backup.