Abdon Pijpelink
45f19f30ee
* Add new Scaling landing page under Operations Introduces a Scaling section with vertical vs. horizontal scaling guidance and failover best practices, linking out to detail pages. * Add new Vertical Scaling page Dedicated how-to guidance for resizing existing nodes: when to scale vertically, RAM sizing formulas, and Cloud/self-hosted resize steps. * Add new Horizontal Scaling and Resilience page Covers Raft consensus, the replication model, consistency guarantees, Multi-AZ, and the resilience terminology used elsewhere in the docs. * Move Distributed Deployment under Scaling and update all incoming links Moves distributed_deployment.md into the new scaling/ section, trims its Raft/Replication/Consistency intros into cross-links to the new Horizontal Scaling and Resilience page, adds Multi-AZ and single-replica cross-link callouts in the Cloud docs, rewrites all internal references across ~30 files to the new canonical path instead of relying on aliases, and applies Title Case to Distributed Deployment's headers. * Split Resilience out of Horizontal Scaling and Resilience Adds a dedicated Resilience page covering fault tolerance, Multi-AZ, resilience terminology, and failover best practices (moved from the Scaling landing page). Horizontal Scaling is retitled and scoped to the underlying mechanics: Raft consensus, replication, and consistency. * Reorganize Horizontal Scaling's structure Moves "How Many Qdrant Nodes Should I Run?" from Distributed Deployment into Horizontal Scaling, adds a conceptual Sharding section, and reorders Sharding/Replication/Raft Consensus/Consistency. Moves the remaining conceptual content out of Distributed Deployment: Temporary Node Failure to Resilience, Error Handling folded into Replication, sharding heuristics folded into Sharding, and the Consensus Checkpointing explanation folded into Raft Consensus. * Rename Scaling section to Scaling & Resilience Renames the section and restructures the landing page: the vertical- vs-horizontal decision is now purely about scaling, with a dedicated Resilience section covering fault tolerance through sharding and multi-node deployments. * Polish Vertical Scaling and Resilience page content Reframes Vertical Scaling's "What Not to Do" as positive "Best Practices". Reworks Resilience's structure: moves the uptime/data- integrity terminology into the intro as three distinct aspects of resilience, and renames "How Resilience Works" to "Setting Up a Resilient Qdrant Cluster". * Add diagrams illustrating sharding and replication Adds cluster diagrams to the Sharding and Replication sections on Horizontal Scaling to make the shard/replica layout easier to follow. * Add new Node Failure Recovery page Extracts the node failure recovery scenarios out of Distributed Deployment into their own page, with each bolded sub-header converted to a proper heading, and links updated across Resilience and the Scaling landing page. * Add new Consistency Guarantees page Extracts write consistency factor, read consistency, and write ordering out of Distributed Deployment into their own page, positioned after Distributed Deployment. * Add new "Deploy Behind a Load Balancer" section Explains why a load balancer is needed in front of a multi-node Qdrant cluster: avoiding a single point of failure at the entry point and making sure replicas on every node actually serve reads. * Add new "Rebalancing" section Documents how Qdrant Cloud automatically rebalances shards across nodes, as its own subsection under Sharding. * Rewrite Multi-AZ vs. Replication Factor as Multi-AZ Deployments Defines an availability zone on first use, explains why multi-AZ deployments guard against a zone going down, clarifies that Qdrant Cloud is zone-aware once enabled, and that self-hosted deployments need to place and move replicas across zones manually. * Restructure node-count guidance into One/Two/Three-or-more Node subsections Splits "How Many Qdrant Nodes Should I Run?" into three subsections and drops the "balanced" framing for two nodes: it states plainly that two nodes give more capacity without true high availability. * Add new "Which Configuration Is Right for You?" section Summarizes the one/two/three-or-more node tradeoffs in one place right after the detailed breakdown. * Add explicit _redirects entry for legacy distributed_deployment URL Closes the redirect chain: the existing /guides/ and /operations/ legacy rules both terminate at /documentation/distributed_deployment/, which previously had no explicit _redirects entry and only resolved via the Hugo alias meta-refresh page. * Fix all incoming links to Distributed Deployment and pages under Scaling Repoints two same-page anchors in distributed_deployment.md that broke when Write Ordering moved to Consistency Guarantees, and one link in cloud/create-cluster.md that broke when a Resilience heading was reworded. * Update time-based sharding diagram and restructure section * Fix a couple of broken links * Move 'Consensus Checkpointing' to 'Node Failure Recovery' page
7.4 KiB
title, short_description, description, weight
| title | short_description | description | weight |
|---|---|---|---|
| Resilience | Configure Qdrant's replication factor, node count, and Multi-AZ settings for fault tolerance, plus failover best practices for production. | Learn how replication factor and node count together determine Qdrant's fault tolerance, how Multi-AZ differs from replication, and how to configure failover for production. | 15 |
Resilience
Qdrant's fault tolerance is driven by replication and node count. Together, they control whether your data survives a node loss and whether your cluster keeps serving requests when one goes down.
Resilience covers three distinct aspects of a Qdrant cluster, and it's worth keeping them separate since a cluster can have one without the others:
- Availability for reading and writing data: whether search and write requests keep succeeding while a node is down. See Temporary Node Failure for exactly how differently-configured clusters behave when a node goes down.
- Availability for cluster-wide operations: whether you can still create, edit, or delete collections while a node is down. This requires a majority of nodes to be healthy, regardless of replication factor. See How many Qdrant nodes should I run? for how this plays out at different cluster sizes.
- Data integrity: whether your data survives the permanent loss of a node. This depends on replication factor and node count together, not on either form of availability.
This page covers what determines Qdrant's fault tolerance and how to configure failover in production. For how the underlying replication and consensus mechanics work, see Horizontal Scaling.
Setting Up a Resilient Qdrant Cluster
Two factors determine the resilience of a Qdrant cluster:
- Replication factor controls how many copies of each shard exist. More copies mean your data survives the loss of more nodes.
- Node count controls how many independent machines those copies can be spread across, and how many nodes can vote in the Raft consensus that manages collection operations.
These two factors work together:
- A high replication factor on a single node cluster is meaningless: Qdrant won't assign multiple copies of the same shard to a single node. More importantly, it leaves you with a single point of failure. If the node fails, the cluster is unavailable. If the node is unrecoverable, you lose data.
- A large node count with a replication factor of one means a single node failure causes unavailability for any collection that had shards on that node. If the node can't be recovered, the data it held is lost, even though the rest of the cluster keeps running.
Resilience comes from provisioning both together: a highly available cluster consists of three or more nodes, and collections should have a replication factor of two or higher.
Temporary Node Failure
Running Qdrant in distributed mode makes your cluster resistant to outages when one node fails temporarily. Here's how differently-configured Qdrant clusters respond:
- 1-node clusters: All operations time out or fail for up to a few minutes, depending on how long it takes to restart and load data from disk.
- 2-node clusters where shards are not replicated: All operations will time out or fail for up to a few minutes, depending on how long it takes to restart and load data from disk.
- 2-node clusters where all shards are replicated to both nodes: All requests except for operations on collections continue to work during the outage.
- 3+-node clusters where all shards are replicated to at least 2 nodes: All requests continue to work during the outage.
For the steps to recover from a permanent node loss, see Node Failure Recovery.
Multi-AZ Deployments
An availability zone (AZ) is an isolated section of a cloud provider's infrastructure, typically a distinct data center or group of data centers within a region, with its own power and networking. A multi-AZ deployment spreads your cluster's nodes across more than one availability zone, so that the loss of a single zone, for example due to a power outage or a network failure, doesn't take down your whole cluster.
Creating a multi-node cluster with replication does not automatically distribute replicas across availability zones: all replicas may land in the same zone, so a single zone outage could take down every replica of a shard at once, even with a replication factor of two or higher.
On the Qdrant Cloud premium tier, checking the Multi AZ box at cluster creation makes Qdrant zone-aware: it automatically distributes shards across availability zones so that each shard has a replica in another zone, and it routes traffic between zones automatically so the cluster stays available if one zone goes down. See Creating a Production-Ready Cluster.
Self-hosted Qdrant clusters have no zone awareness and won't automatically distribute replicas across them. You need to spread your nodes across zones yourself, then move replicas so that each shard has at least one replica in a different zone.
Failover Best Practices
How Qdrant responds to a node failure depends entirely on how the cluster is provisioned beforehand:
- Run at least three nodes with a replication factor of two or more in production. A single-replica cluster, which is the default, gets none of Qdrant's high-availability guarantees: no automatic failover, no Multi-AZ protection, and no zero-downtime upgrades. All of these depend on having replicated data spread across multiple nodes.
- Enable Multi-AZ if you need protection against a zone-level outage. Replication alone doesn't guarantee that your nodes, and therefore your replicas, are spread across separate availability zones. Multi-AZ must be enabled explicitly at cluster creation.
- Self-hosted Qdrant does not fail over automatically. If a node fails permanently, you need to remove it from consensus and attach a replacement node yourself. See Node Failure Recovery for the recovery steps.
- Qdrant Cloud (Managed, Hybrid, and Private) adds automatic failover on top of replication, so Qdrant Cloud detects and replaces a failed node without manual intervention, provided your cluster has enough replicas to tolerate the loss.
- Monitor cluster health so you can react before a second failure compounds the first. See Monitoring & Telemetry for setting up Prometheus and Grafana against your cluster.
Where to Go Next
- Horizontal Scaling covers Raft consensus, the replication model, and consistency guarantees.
- Distributed Deployment covers the practical configuration: enabling distributed mode, sharding, replication, and node failure recovery.
- Node Failure Recovery covers the steps to remove a permanently failed node from consensus and attach a replacement.