Skip to main content
skill CX Codex

qdrant-hybrid-cloud-setup — Claude Code skill: setup

The qdrant-hybrid-cloud-setup Claude Code skill guides Qdrant Hybrid Cloud deployment on a self-managed Kubernetes cluster. It activates for agent and operator setup, storage and backups, or cluster access configuration.

Apache-2.0 121 installs ★ 271 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add qdrant/skills --skill qdrant-hybrid-cloud-setup -a claude-code
Open on GitHub

What qdrant-hybrid-cloud-setup does

The skill walks through running Qdrant Hybrid Cloud on your own Kubernetes infrastructure, from preparing the environment and installing the agent and operator to provisioning and securing a cluster. It also covers secret rotation and troubleshooting storage or connectivity failures.

Qdrant requires a block-storage CSI driver; NFS and S3 storage are unsupported. Create a StorageClass with allowVolumeExpansion: true and a VolumeSnapshotClass before installation. Setup also requires cluster-admin access and configured kubectl and helm. The agent needs outbound connections to grpc.cloud.qdrant.io and api.cloud.qdrant.io on port 443.

The skill explains snapshot and storage-class choices, plus external access through a LoadBalancer, NodePort, or Ingress. Exposed clusters need an API key, while internal gRPC traffic on port 6335 must not be reachable from the public internet. Backups on Linode and Vultr depend on whether the platform supports CSI volume snapshots.

What it helps with

  • prepare Kubernetes storage for Qdrant
  • install the Hybrid Cloud agent and operator
  • diagnose an agent that cannot connect to Qdrant Cloud
  • configure external cluster access and an API key
  • check platform support for CSI volume snapshots

Example prompts for the agent

  • Help me deploy Qdrant Hybrid Cloud on my Kubernetes cluster.
  • The Hybrid Cloud agent is stuck during installation; check storage and connectivity.
  • How do I expose a Qdrant cluster through Ingress and configure its API key?

How to install qdrant-hybrid-cloud-setup

1Skills CLI (Vercel)

npx skills add qdrant/skills --skill qdrant-hybrid-cloud-setup -a claude-code

2Manually: put the files in place

~/.claude/skills/qdrant-hybrid-cloud-setup/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/qdrant-hybrid-cloud-setup/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about qdrant-hybrid-cloud-setup

How do I install qdrant-hybrid-cloud-setup in Claude Code?

Run npx skills add qdrant/skills --skill qdrant-hybrid-cloud-setup -a claude-code. The skill file is at ~/.claude/skills/qdrant-hybrid-cloud-setup/SKILL.md.

What does qdrant-hybrid-cloud-setup do?

It guides Qdrant Hybrid Cloud setup on a self-managed Kubernetes cluster, covering storage, the agent and operator, cluster provisioning, security, and external access.

What does qdrant-hybrid-cloud-setup require?

You need a Kubernetes cluster with a block-storage CSI driver, cluster-admin access, and configured kubectl and helm. The agent needs outbound access to grpc.cloud.qdrant.io and api.cloud.qdrant.io on port 443.

Source text

SKILL.md · Apache-2.0
---
name: qdrant-hybrid-cloud-setup
description: "Setting up and running Qdrant Hybrid Cloud on your own Kubernetes cluster (managed, on-prem, or edge): prerequisites, storage/CSI and backups, installing the Qdrant Cloud agent and operator, creating/exposing/securing clusters, registry mirroring, and secret rotation. Use when someone wants to set up, install, deploy, or configure Hybrid Cloud on their own infrastructure; is running Qdrant on their own EKS, GKE, AKS, OpenShift, or other Kubernetes; asks about the agent or operator, a storage class or volume snapshots for Hybrid Cloud, exposing a cluster, mirroring Qdrant images, or rotating secrets; or when a Hybrid Cloud install is failing on storage or connectivity."
---

# Setting Up Qdrant Hybrid Cloud

You've already chosen Hybrid Cloud (managed control plane on your own infra). If you're still deciding, that's the `qdrant-deployment-options` skill. Most setup failures trace to one of two things: **storage** (the CSI driver can't do what Qdrant needs) or **connectivity** (the agent can't reach Qdrant Cloud). Diagnose which before touching anything else.

## Preparing the Kubernetes cluster (do this first)

Use when: about to create the environment, or the install/cluster provisioning failed on storage.

- Qdrant needs a block-storage CSI driver. Network storage (NFS) and object storage (S3) are unsupported: a cluster wired to those will fail, not degrade [Prerequisites](https://skills.qdrant.tech/md/documentation/hybrid-cloud/hybrid-cloud-setup/).
- Create the `StorageClass` (with `allowVolumeExpansion: true`) and the `VolumeSnapshotClass` *beforehand*, not after. Without volume expansion you can't grow disk later; without a `VolumeSnapshotClass` and the CSI snapshot controller you can't take backups.
- Any standards-compliant Kubernetes works; check the [Deployment Platforms](https://skills.qdrant.tech/md/documentation/hybrid-cloud/platform-deployment-options/) page for your managed provider's setup guidance.
- Platform matters for what storage supports: some (e.g. Linode/LKE, Vultr) don't support CSI volume snapshots at all, so backups are unavailable there. Check your provider's snapshot page and prefer its recommended instance and disk types (e.g. gp3 on EKS, Premium SSD v2 on AKS) before committing.
- Confirm outbound connectivity: the agent opens connections to `grpc.cloud.qdrant.io` and `api.cloud.qdrant.io` on 443. Firewalls/egress proxies block this silently: a "stuck installing" agent is usually this.
- You need `cluster-admin` plus `kubectl` and `helm` configured against the target cluster.

## Creating the environment

Use when: running the install wizard in the Cloud Console.

- The **Kubernetes namespace is permanent**: it's the one choice you can't change later. Everything else (node selectors, tolerations, registry URLs, proxy) is editable after creation, so don't over-think them now.
- The wizard's install command is for the initial install only; update the agent and operator from the Console afterward [Generate installation command](https://skills.qdrant.tech/md/documentation/hybrid-cloud/hybrid-cloud-setup/?s=generate-installation-command).
- Advanced operator behavior (pod scheduling, security context, ingress, networking, and snapshot management) is tuned in the operator configuration at the environment level, and can be changed after install [Operator configuration](https://skills.qdrant.tech/md/documentation/hybrid-cloud/operator-configuration/).
- Air-gapped or registry-restricted? Mirror the `/qdrant/` images and `/qdrant-charts/` charts into your own registry and set the container + chart URLs in the environment's advanced section. Sync *all* architectures (or the right one) or ARM/x86 nodes will fail to pull.

## Creating a cluster in the environment

Use when: the environment exists and you're provisioning a database.

- Pick the Database Storage Class and Volume Snapshot Class here. Setting Volume Snapshot Class to `None` disables backups; `emptyDir` for the snapshot volume makes it ephemeral (lost on pod restart): deliberate choices, not defaults to accept blindly [Cluster creation](https://skills.qdrant.tech/md/documentation/hybrid-cloud/hybrid-cloud-cluster-creation/).
- By default Qdrant Cloud reserves ~20% CPU/memory per pod for the OS and system components. Small nodes may need more reserved; large nodes less. Aim for one database pod per node.
- Use node selectors / tolerations / topology spread constraints to keep databases on dedicated nodes and spread across zones.

## Exposing and securing a cluster

Use when: apps outside the Kubernetes cluster need to reach Qdrant, or asked about API keys/TLS.

- Default is a `ClusterIP` service: internal-only, **no API key**. The moment you expose it (LoadBalancer, NodePort, or Ingress) you MUST configure an API key, supplied as a Kubernetes secret referenced in the cluster config [Authentication](https://skills.qdrant.tech/md/documentation/hybrid-cloud/hybrid-cloud-cluster-creation/?s=authentication-to-your-qdrant-clusters).
- Internal node-to-node gRPC uses port 6335 and is never protected by API key or TLS. It must never be publicly reachable; Hybrid Cloud ships a NetworkPolicy restricting it, so don't loosen that.
- TLS: offload at the ingress/LB, or terminate in Qdrant via a TLS secret. Don't do both by accident.

## Logging

Use when: setting log levels or wiring cluster logs into your stack. (For metrics/Prometheus/Grafana, use the `qdrant-monitoring` skill instead.)

- Log levels are set in two different places: per-database in the Cluster detail page, but for the **Agent and Operator** in the Hybrid Cloud Environment config, not per-cluster [Networking, Logging & Monitoring](https://skills.qdrant.tech/md/documentation/hybrid-cloud/networking-logging-monitoring/).
- Logs are plain pod logs with no Qdrant-specific format. Point any Kubernetes-aware log collector at all pods in the Qdrant namespace; nothing Qdrant-specific to configure.

## What NOT to Do

- Provision on NFS, S3, or any non-block storage: it's unsupported and will fail outright, not just run slowly.
- Create the `StorageClass`/`VolumeSnapshotClass` (or enable `allowVolumeExpansion`) after the fact, then discover you can't scale disk or take backups. They must exist beforehand.
- Assume backups "just work" on Linode or Vultr: verify CSI snapshot support for your platform first.
- Expose a cluster via LoadBalancer/Ingress without setting an API key, or leave port 6335 publicly reachable.
- Regenerate the install command (or rotate secrets) and forget to reapply it: the agent-to-Cloud link breaks silently until you do.
- Delete a Hybrid Cloud environment before deleting its clusters: tear down clusters first, then the environment, then run the cleanup script, or you'll strand resources in the cluster.

© qdrant · Apache-2.0 · qdrant/skills

Similar skills

All skills for Cloud: AWS, Azure, GCP →
google-cloud-solution-hybrid-search-alloydb official google The google-cloud-solution-hybrid-search-alloydb skill helps design and validate AlloyDB hybrid search, combining semantic retrieval with keyword search and structured SQL filters. CX Codex +1 3,300installs hybrid-cloud-architect sickn33 The hybrid-cloud-architect skill helps plan hybrid infrastructure across AWS, Azure, GCP, and private clouds. Use it for connectivity, workload placement, migrations, Kubernetes, and disaster recovery. CX Codex +1 1installs google-cloud-solution-rag-enterprise-search-gke-sqldb official google google-cloud-solution-rag-enterprise-search-gke-sqldb is a Claude Code skill for designing enterprise RAG search on Google Cloud. It gathers requirements for systems using vector-enabled SQL, an open model, and Kubernetes-hosted components. CX Codex +1 5,000installs domain-cloud-native actionbook domain-cloud-native — a domain skill that injects cloud-native architecture rules into Rust projects, covering health endpoints, graceful exits, and stateless design. CX Codex +1 3,200installs sap-btp-cloud-platform secondsky sap-btp-cloud-platform — a reference skill for SAP Business Technology Platform: accounts, Cloud Foundry, Kyma, ABAP Environment, MTA deployments and on-premise connectivity. CX Codex +1 825installs huawei-cloud-cce-cluster-management huaweicloud huawei-cloud-cce-cluster-management is a Claude Code skill for managing Huawei Cloud CCE clusters, nodes, node pools, and addons during routine Kubernetes operations. CX Codex +1 293installs

From the same set12

The whole set →
qdrant-version-upgrade The qdrant-version-upgrade Claude Code skill guides Qdrant server and SDK upgrades with version compatibility in mind. It covers upgrade sequencing, multi-version jumps, and behavior changes after a release. CX Codex +1 1,400installs qdrant-performance-optimization qdrant-performance-optimization — a routing skill for Qdrant tuning: it matches your symptom to the right sub-skill for search speed, indexing or memory. CX Codex +1 1,700installs qdrant-advisor qdrant-advisor fetches official troubleshooting guidance live from skills.qdrant.tech to diagnose vector search latency, memory spikes, and sharding issues. CX Codex +1 782installs qdrant-edge This Claude Code skill guides development with Qdrant Edge. It covers local shard sync, BM25 search, and index maintenance. CX Codex +1 328installs qdrant-multitenancy qdrant-multitenancy — a skill for Claude Code, Codex, and Cursor. Guides tenant isolation architecture across users in Qdrant vector databases. CX Codex +1 298installs qdrant-sizing qdrant-sizing calculates RAM, disk space, CPU cores, and node count for a Qdrant deployment before hardware or cloud instances are provisioned. CX Codex +1 222installs qdrant-migration-tool The qdrant-migration-tool skill facilitates migrating vector data and metadata from various databases into Qdrant. It orchestrates the migration process, handles data streaming, and manages resume capabilities. CX Codex +1 137installs qdrant-skills This plugin gives the agent Qdrant guidance for scaling, search quality, SDK work, deployments, monitoring, and model changes. ★ 271repo stars

Project sponsors

Companies that keep this analytics open