Configure, Scale & Update Qdrant Hybrid Cloud Clusters

You manage Hybrid Cloud clusters in the Qdrant Cloud Console, with the qcloud CLI, the Cloud API, or Terraform. The Operator in your Kubernetes cluster applies the change. Change cluster resources through one of these tools, and not with kubectl, because the Operator owns the numbers.

Configure Clusters

Hybrid Cloud clusters have the settings of a Managed Cloud cluster, such as collection defaults and strict mode. See Configure Clusters. They also have settings that control how the pods run in your Kubernetes cluster:

SettingFind it in
Node selectors, tolerations, and topology spread constraintsScheduling Configuration
API key and read-only API key from a Kubernetes secretAuthentication
Service type, service annotations, and load balancer source rangesExposing Qdrant clusters
TLSConfiguring TLS
Storage class, snapshot storage class, and volume snapshot classCreate a Cluster
CPU and memory reservationResource reservations

These changes restart the pods one at a time in a rolling restart:

  • Version upgrades
  • Database settings, such as the replication factor, the write consistency factor, the async scorer, the optimizer CPU budget, vectors on disk, the log level, audit logging, TLS, and the API key secrets
  • Pod settings, such as the service type, node selectors, tolerations, topology spread constraints, annotations, pod labels, service annotations, the reserved CPU and memory percentages, and the storage classes

These changes take effect without a restart: allowed IP ranges, the restart mode, the shard rebalance strategy, the cost allocation label, and cluster labels.

Scale Clusters

ChangeRestartNotes
CPU or memory, up or downAlwaysQdrant reads its memory and CPU count once, at startup, so the Operator restarts the pods
Disk, increaseNo, by defaultUses online volume expansion. Whether the resize is online depends on your storage provider, and most cloud providers support it. If your storage needs a restart, as with some Azure disks, set volumeExpansionMode to Offline in the Operator configuration. The default is Online
Disk, decreaseEach node is replacedNeeds Qdrant v1.19.2 or later and an Operator that supports it. Each node is replaced by a smaller one and its shard data is transferred. This deletes the local snapshots of the cluster, so copy any you need first. With the CLI, pass --allow-disk-decrease and --force
Number of nodesSee Scale Clusters for shard rebalancing and resharding

Online disk expansion needs a StorageClass with volume expansion enabled. See Deployment Platforms for your platform.

To scale, use the Console or the CLI. For example, to set the memory and the disk, and then only the CPU:

qcloud cluster scale <CLUSTER_ID> --ram 4GiB --disk 16GiB
qcloud cluster scale <CLUSTER_ID> --cpu 1000m

On a multi-node cluster with replicated collections, a restart rolls through the nodes one at a time and the cluster stays available. A single-node cluster, or a collection without replicas, is briefly unavailable while its pod restarts.

Before You Scale

  • Make sure the nodes have room. Hybrid Cloud does not add nodes to your Kubernetes cluster. The node pool needs capacity for the new pod size, and ideally one database pod fits one node.
  • Check the actual usage. Look at CPU throttling with container_cpu_cfs_throttled_periods_total, memory with container_memory_working_set_bytes against the pod limit, and disk with kubelet_volume_stats_used_bytes against kubelet_volume_stats_capacity_bytes. See Networking, Logging & Monitoring.

Resource Reservation

Qdrant Cloud reserves 20% of the CPU and memory of each pod for the operating system, Kubernetes, and system components. Qdrant can use the rest. The pod requests and limits are equal, and they match the available amount. You can change the reservation in the Configuration section of the cluster detail page. Smaller nodes can need a larger reservation, and larger nodes a smaller one.

qcloud cluster describe <CLUSTER_ID> shows the base, reserved, and available CPU and memory per node. The reservation is stored in the Cloud control plane, so kubectl get qdrantcluster does not show it.

Update Clusters

Qdrant Version

Update the version in the Console, or with the CLI:

qcloud cluster version list
qcloud cluster update <CLUSTER_ID> --version <VERSION>

A version update is a rolling restart. On a replicated multi-node cluster it runs with no downtime. If you mirror the images and charts, keep the mirror in sync so that new versions are available in your registry. See Mirroring images and charts. For the checks to run before and after, see Update Clusters.

Operator and Agent

Qdrant Cloud updates the Operator and the Cloud Agent automatically, through the built-in Helm controller. The updates are tested, and you cannot defer or roll them back. They are frequent, because the components in your cluster must stay compatible with the Qdrant Cloud management plane.

Was this page useful?

Thank you for your feedback! 🙏

We are sorry to hear that. 😔 You can edit this page on GitHub, or create a GitHub issue.