Qdrant (qdrant)
Vector database for the embeddings of the retrieval pipelines. Single node or distributed with Raft consensus and sharded collections.
Generated from catalog/services/qdrant.yaml: do not edit by hand.
Summary
| Version | 1.14.1 |
| Use | install and configure, configure and connect |
| Layer | functional (AI catalog) |
| Category | Data platforms |
| Installation methods | binary, podman |
| External connection | qdrant |
| Sandbox only | no |
Licence
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Platform component | qdrant |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| container image | docker.io/qdrant/qdrant | v1.14.1 | Apache-2.0 | image key qdrant, used by node, digest sha256:419d72603f5346ee22ffc4606bdb7beb52fcb63077766fab678e6622ba247366 |
| binary archive | qdrant-x86_64-unknown-linux-gnu.tar.gz | 1.14.1 | Apache-2.0 | https://github.com/qdrant/qdrant/releases/download/v1.14.1/qdrant-x86_64-unknown-linux-gnu.tar.gz, x86_64 |
Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
binary | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64 (architecture of the artifacts of the descriptor) |
podman | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- at least 2048 MB of memory (blocking,
memory).
Programs the commands and checks of the service start on the host, outside the managed roots: add them to allowed_commands of the agent (see Security of the Navin agent), else the agent refuses them with command_not_allowed: /usr/bin/curl.
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
node | http | 6333/tcp | yes |
node | grpc | 6334/tcp | yes |
node | p2p | 6335/tcp | yes |
Services and connections needed
This service has no dependency.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
binary | yes | the binary archives of the descriptor, unpacked under the service directory |
podman | - | the container images of the descriptor, run by Podman under systemd |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
Qdrant node (node) | master | binary, podman | 6333/tcp, 6334/tcp, 6335/tcp |
Single node (standalone) (default)
One Qdrant node.
What the mode deploys:
| Component | Placement |
|---|---|
node | min 1, max 1 |
Distributed (distributed)
Nodes joined by Raft, bootstrapped from the first node; an odd count keeps the quorum.
What the mode deploys:
| Component | Placement |
|---|---|
node | min 3, odd number, recommended 3 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select Qdrant. The card shows the licence
Apache-2.0. Pick the Method amongbinary,podman(defaultbinary). To register an existingqdrantservice of your organisation instead, turn on Use an existing external service. -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
standalone(default),distributed. Each mode deploys the components listed in Installation methods and modes. -
Bindings. This service has no dependency: the Bindings step has nothing to bind.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
Connect an existing service
| Schemes | https, http |
| Default port | 6333 |
| Authentication | optional |
| Health check | /healthz |
| Authentication method | Fields | Description |
|---|---|---|
api_key | api_key | Admin key (service.api_key) or read only key (service.read_only_api_key), sent in the api-key header. |
jwt | token | Granular access token (JWT of service.jwt_rbac) signed with the admin key. |
none | - | Without an API key Qdrant is open to anyone who reaches it: development only. |
Official documentation: https://qdrant.tech/documentation/security/
High availability
| Cluster | native (native) |
| High availability | native (native) |
| Failover | native (native) |
| Replication | native (native) |
| Quorum | Raft (raft) |
| Discovery | static (static) |
| Entry point | any node (any-node) |
| Official documentation | https://qdrant.tech/documentation/distributed_deployment/ |
| Peer TLS parameter | tls_enabled |
| Cluster status command | cluster_info |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
standalone | standalone (standalone) | single (single) | - | 1 | One Qdrant node. |
distributed | cluster (cluster) | active-active (active-active) | node | 3 | Nodes joined by Raft from the first node; collections created with a replication factor of 2. |
Notes
- Qdrant OSS needs an explicit configuration of the replication and of the shard rebalancing: it is not the managed high availability of Qdrant Cloud. The catalog sets a default replication factor of 2 for new collections; moving shards after a node change is an operator action.
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
HTTP port (http_port) | port | 6333 | - | no | no | no | Port of the REST API and /metrics. |
gRPC port (grpc_port) | port | 6334 | - | no | no | no | Port of the gRPC API. |
Peer port (p2p_port) | port | 6335 | - | no | no | no | Port of the internal traffic between nodes (distributed mode). |
Storage
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Payload on disk (on_disk_payload) | bool | true | - | no | no | no | Keep payloads on disk to save memory. |
Shards per collection (default_shard_number) | int | 1 | min 1, max 64 | no | no | no | Default shard count of new collections, one per node. (recommended len(topology.node)) |
Security
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
TLS (tls_enabled) | bool | false | - | no | no | no | Serve the APIs and the peer traffic over TLS with the manager CA certificate. |
API key (api_key) | password | generated | - | no | yes | no | Key required by every API call. |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|---|---|---|---|---|---|---|---|
http | http | node | 6333 (http_port) | - | tls_enabled | - | api_key | - |
grpc | grpc | node | 6334 (grpc_port) | - | tls_enabled | - | api_key | - |
Commands
| Command | Component | Target | Description |
|---|---|---|---|
Cluster status (cluster_info) | node | every host | Checks the Raft state and the peers seen by every node. |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
node | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.http_port }}/healthz | Expected 200; 60 retries |
Readiness (service check)
| Check | Details |
|---|---|
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.http_port }}/readyz | Expected 200 |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|---|---|---|---|
memory | memory_mb {"min": 2048} | at least 2048 MB of memory | blocking | every component |
http_port_free | port_free {"param": "http_port"} | port 6333 free on the host | blocking | every component |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Quick links
- Web UI:
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.http_port }}/dashboard
Upstream documentation
- Homepage: https://qdrant.tech
- Source: https://github.com/qdrant/qdrant
- High availability: https://qdrant.tech/documentation/distributed_deployment/
- Authentication: https://qdrant.tech/documentation/security/