Skip to content

Commit

Permalink
chore: update qdrant examples (#1321)
Browse files Browse the repository at this point in the history
  • Loading branch information
@shanshanying
shanshanying authored Dec 16, 2024
1 parent 2e44434 commit f0be351
Show file tree
Hide file tree
Showing 14 changed files with 326 additions and 204 deletions.
253 changes: 198 additions & 55 deletions examples/qdrant/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,122 +2,265 @@

Qdrant is an open source (Apache-2.0 licensed), vector similarity search engine and vector database.

## Prerequisites
## Features In KubeBlocks

This example assumes that you have a Kubernetes cluster installed and running, and that you have installed the kubectl command line tool and helm somewhere in your path. Please see the [getting started](https://kubernetes.io/docs/setup/) and [Installing Helm](https://helm.sh/docs/intro/install/) for installation instructions for your platform.
### Lifecycle Management

Also, this example requires kubeblocks installed and running. Here is the steps to install kubeblocks, please replace "`$kb_version`" with the version you want to use.
```bash
# Add Helm repo
helm repo add kubeblocks https://apecloud.github.io/helm-charts
# If github is not accessible or very slow for you, please use following repo instead
helm repo add kubeblocks https://jihulab.com/api/v4/projects/85949/packages/helm/stable
| Topology | Horizontal<br/>scaling | Vertical <br/>scaling | Expand<br/>volume | Restart | Stop/Start | Configure | Expose | Switchover |
|------------------|------------------------|-----------------------|-------------------|-----------|------------|-----------|--------|------------|
| cluster | Yes | Yes | Yes | Yes | Yes | No | Yes | N/A |

# Update helm repo
helm repo update
### Backup and Restore

# Get the versions of KubeBlocks and select the one you want to use
helm search repo kubeblocks/kubeblocks --versions
# If you want to obtain the development versions of KubeBlocks, Please add the '--devel' parameter as the following command
helm search repo kubeblocks/kubeblocks --versions --devel
| Feature | Method | Description |
|-------------|--------|------------|
| Full Backup | datafile | uses HTTP API `snapshot` to create snapshot for all collections. |

# Create dependent CRDs
kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v$kb_version/kubeblocks_crds.yaml
# If github is not accessible or very slow for you, please use following command instead
kubectl create -f https://jihulab.com/api/v4/projects/98723/packages/generic/kubeblocks/v$kb_version/kubeblocks_crds.yaml
### Versions

# Install KubeBlocks
helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace --version="$kb_version"
```
Enable qdrant
```bash
# Add Helm repo
helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts
# If github is not accessible or very slow for you, please use following repo instead
helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable
# Update helm repo
helm repo update
| Major Versions | Description |
|---------------|-------------|
| 1.5 | 1.5.0 |
| 1.7 | 1.7.3 |
| 1.8 | 1.8.1,1.8.4 |
| 1.10| 1.10.0 |

## Prerequisites

# Enable qdrant
helm upgrade -i kb-addon-qdrant kubeblocks-addons/qdrant -n kb-system --version $kb_version
```
- Kubernetes cluster >= v1.21
- `kubectl` installed, refer to [K8s Install Tools](https://kubernetes.io/docs/tasks/tools/)
- Helm, refer to [Installing Helm](https://helm.sh/docs/intro/install/)
- KubeBlocks installed and running, refer to [Install Kubeblocks](../docs/prerequisites.md)
- Qdrant Addon Enabled, refer to [Install Addons](../docs/install-addon.md)

## Examples

### [Create](cluster.yaml)
Create a qdrant cluster with specified cluster definition
### [Create](cluster.yaml)

Create a Qdrant cluster with specified cluster definition

```bash
kubectl apply -f examples/qdrant/cluster.yaml
```
Starting from kubeblocks 0.9.0, we introduced a more flexible cluster creation method based on components, allowing customization of cluster topology, functionalities and scale according to specific requirements.

### [Horizontal scaling](horizontalscale.yaml)

> [!Important]
> Qdrant uses the **Raft consensus protocol** to maintain consistency regarding the cluster topology and the collections structure.
> Make sure to have an odd number of replicas, such as 3, 5, 7, to avoid split-brain scenarios, after scaling out/in the cluster.
#### [Scale-out](scale-out.yaml)

Horizontal scaling out cluster by adding ONE more replica:

```bash
kubectl apply -f examples/qdrant/cluster-cmpd.yaml
kubectl apply -f examples/qdrant/scale-out.yaml
```
### [Horizontal scaling](horizontalscale.yaml)
Horizontal scaling out or in specified components replicas in the cluster

#### [Scale-in](scale-in.yaml)

Horizontal scaling in cluster by deleting ONE replica:

```bash
kubectl apply -f examples/qdrant/horizontalscale.yaml
kubectl apply -f examples/qdrant/scale-in.yaml
```

> [!IMPORTANT]
> On scale-in, data will be redistributed among the remaining replicas. Make sure to have enough capacity to accommodate the data.
> The data redistribution process may take some time depending on the amount of data.
> It is handled by Qdrant `MemberLeave` operation, and Pods won't be deleted until the data redistribution, i.e. the `MemberLeave` actions completed successfully.
#### Scale-in/out using Cluster API

Alternatively, you can update the `replicas` field in the `spec.componentSpecs.replicas` section to your desired non-zero number.

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
name: qdrant-cluster
namespace: default
spec:
componentSpecs:
- name: qdrant
replicas: 3 # Update `replicas` to your desired number
```
### [Vertical scaling](verticalscale.yaml)
Vertical scaling up or down specified components requests and limits cpu or memory resource in the cluster
```bash
kubectl apply -f examples/qdrant/verticalscale.yaml
```

#### Scale-up/down using Cluster API

Alternatively, you may update `spec.componentSpecs.resources` field to the desired resources for vertical scale.

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
name: qdrant-cluster
namespace: default
spec:
componentSpecs:
- name: qdrant
componentDef: qdrant
replicas: 3
resources:
requests:
cpu: "1" # Update the resources to your need.
memory: "2Gi" # Update the resources to your need.
limits:
cpu: "2" # Update the resources to your need.
memory: "4Gi" # Update the resources to your need.
```
### [Expand volume](volumeexpand.yaml)
> [!NOTE]
> Make sure the storage class you use supports volume expansion.
Check the storage class with following command:
```bash
kubectl get storageclass
```

If the `ALLOWVOLUMEEXPANSION` column is `true`, the storage class supports volume expansion.

To increase size of volume storage with the specified components in the cluster

Increase size of volume storage with the specified components in the cluster

```bash
kubectl apply -f examples/qdrant/volumeexpand.yaml
```

#### Volume expansion using Cluster API

Alternatively, you may update the `spec.componentSpecs.volumeClaimTemplates.spec.resources.requests.storage` field to the desired size.

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
name: qdrant-cluster
namespace: default
spec:
componentSpecs:
- name: qdrant
componentDef: qdrant
replicas: 3
volumeClaimTemplates:
- name: data
spec:
storageClassName: ""
accessModes:
- ReadWriteOnce
resources:
requests:
# specify new size, and make sure it is larger than the current size
storage: 30Gi
```
### [Restart](restart.yaml)
Restart the specified components in the cluster
```bash
kubectl apply -f examples/qdrant/restart.yaml
```

### [Stop](stop.yaml)

Stop the cluster and release all the pods of the cluster, but the storage will be reserved

```bash
kubectl apply -f examples/qdrant/stop.yaml
```

### [Start](start.yaml)

Start the stopped cluster

```bash
kubectl apply -f examples/qdrant/start.yaml
```

### [BackupRepo](backuprepo.yaml)
BackupRepo is the storage repository for backup data, using the full backup and restore function of KubeBlocks relies on BackupRepo
### [Backup](backup.yaml)

> [!NOTE] Before you start, please create a `BackupRepo` to store the backup data. Refer to [BackupRepo](../docs/create-backuprepo.md) for more details.
The backup method uses the `snapshot` API to create a snapshot for all collections. It works as follows:

- Retrieve all Qdrant collections
- For each collection, create a snapshot, validate the snapshot, and push it to the backup repository

To create a backup for the cluster:

```bash
# Create a secret to save the access key
kubectl create secret generic <storage-provider>-credential-for-backuprepo\
--from-literal=accessKeyId=<ACCESS KEY> \
--from-literal=secretAccessKey=<SECRET KEY> \
-n kb-system

kubectl apply -f examples/qdrant/backuprepo.yaml
kubectl apply -f examples/qdrant/backup.yaml
```

### [Backup](backup.yaml)
Create a backup for the cluster
After the operation, you will see a `Backup` is created

```bash
kubectl apply -f examples/qdrant/backup.yaml
kubectl get backup -l app.kubernetes.io/instance=qdrant-cluster
```

and the status of the backup goes from `Running` to `Completed` after a while. And the backup data will be pushed to your specified `BackupRepo`.

### [Restore](restore.yaml)
Restore a new cluster from backup
```bash
# Get backup connection password
kubectl get backup qdrant-cluster-backup -ojsonpath='{.metadata.annotations.dataprotection\.kubeblocks\.io\/connection-password}' -n default

To restore a new cluster from backup:

```bash
kubectl apply -f examples/qdrant/restore.yaml
```

The restore methods uses Qdrant HTTP API to restore snapshots to the new cluster, when the restore is completed, the new cluster will be ready to use.

### Observability

There are various ways to monitor the cluster. Here we use Prometheus and Grafana to demonstrate how to monitor the cluster.

#### Installing the Prometheus Operator

You may skip this step if you have already installed the Prometheus Operator.
Or you can follow the steps in [How to install the Prometheus Operator](../docs/install-prometheus.md) to install the Prometheus Operator.

#### Create PodMonitor

##### Step 1. Create PodMonitor

Apply the `PodMonitor` file to monitor the cluster:

```bash
kubectl apply -f examples/qdrant/pod-monitor.yaml
```

It sets path to `/metrics` and port to `tcp-qdrant` (for container port `6333`).

```yaml
- path: /metrics
port: tcp-qdrant
scheme: http
```
##### Step 2. Accessing the Grafana Dashboard
Login to the Grafana dashboard and import the dashboard, e.g. using dashboard from [Grafana](https://grafana.com/grafana/dashboards).
> [!Note]
> Make sure the labels are set correctly in the `PodMonitor` file to match the dashboard.

### Delete

If you want to delete the cluster and all its resource, you can modify the termination policy and then delete the cluster

```bash
kubectl patch cluster qdrant-cluster -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge"
Expand Down
41 changes: 0 additions & 41 deletions examples/qdrant/cluster-cmpd.yaml
View file

This file was deleted.

Loading

0 comments on commit f0be351

Please sign in to comment.