> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes deployment guide

> Learn how LanceDB Enterprise deploys on Kubernetes with private networking, object storage, and workload identity.

LanceDB Enterprise deploys on a Kubernetes cluster (AKS, EKS, GKE, or self-managed) with object storage for data
persistence and your cloud's private networking for secure connectivity. The architecture below is the same shape
on every cloud; the only cloud-specific part is how storage containers are organized, covered at the end of this
page for Azure Blob Storage.

## General architecture overview

```mermaid theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
%%{init: {"theme": "base", "themeVariables": {
  "background": "#ffffff", "primaryColor": "#ffffff", "primaryTextColor": "#221d19",
  "primaryBorderColor": "#ad9e95", "lineColor": "#6b625c", "textColor": "#221d19",
  "clusterBkg": "#f4ebe8", "clusterBorder": "#ad9e95", "edgeLabelBackground": "#ffffff",
  "fontFamily": "Inter, sans-serif", "fontSize": "18px"
}}}%%
graph TB
    subgraph "Client VPC"
        Client[Client Applications]
    end

    subgraph "Server VPC"
        PLS[Private Link Service]

        subgraph "Kubernetes Cluster"
            LDB[LanceDB Enterprise<br/>Query Nodes, Executors,<br/>Lance Agent, Indexer Pods]
        end

        EH[Message Queue<br/>for LanceDB internal<br/>message passing]

        BS[Object Storage]

        WI[Workload Identity]
    end

    Client ==>|Private Link| PLS
    PLS ==> LDB
    LDB <-->|Read/Write| BS
    LDB -->|Async Events| EH
    EH -->|Process| LDB

    WI -.->|RBAC| BS
    WI -.->|Assigned| LDB
    classDef default fill:#ffffff,stroke:#ad9e95,stroke-width:1px,color:#221d19
    classDef accent fill:#fff1ec,stroke:#e8582d,stroke-width:1.5px,color:#221d19
    class LDB accent
```

### Key components

* **LanceDB architecture** is deployed in a Kubernetes cluster within its own VPC.
* **Client applications** connect to the cluster securely using your cloud's private link service.
* **The cluster** is granted object storage read/write permissions using cloud-native workload identity (Azure
  Workload Identity, IRSA on EKS, or Workload Identity Federation on GKE).
* **A message queue** -- a managed service such as Azure EventHub, or a self-hosted Kafka cluster in Kubernetes --
  carries LanceDB's internal message passing.

## Read path architecture

```mermaid theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
%%{init: {"theme": "base", "themeVariables": {
  "background": "#ffffff", "primaryColor": "#ffffff", "primaryTextColor": "#221d19",
  "primaryBorderColor": "#ad9e95", "lineColor": "#6b625c", "textColor": "#221d19",
  "clusterBkg": "#f4ebe8", "clusterBorder": "#ad9e95", "edgeLabelBackground": "#ffffff",
  "fontFamily": "Inter, sans-serif", "fontSize": "18px"
}}}%%
graph LR
    subgraph "Client Network"
        C[Client App]
    end

    subgraph "Kubernetes Cluster"
        PL[Private Link<br/>Service]
        QN[Query Nodes<br/>Query planning + routing fleet]
        PE[Executors<br/>Executor + cache fleet]
    end

    subgraph "Storage"
        BS[Object<br/>Storage]
    end

    C -->|Private<br/>Connection| PL
    PL --> QN
    QN -->|Query<br/>Request| PE
    PE -->|Cache Miss<br/>Read Data| BS
    classDef default fill:#ffffff,stroke:#ad9e95,stroke-width:1px,color:#221d19
    classDef accent fill:#fff1ec,stroke:#e8582d,stroke-width:1.5px,color:#221d19
    class BS accent
```

### Read path flow

1. **Client application** sends a query request through the private link.
2. **Query nodes** receive and process the request.
3. **Executors** execute the query using the distributed data cache to speed up read queries.
4. **Object storage** stores data and indices in Lance format, while executors maintain a distributed cache
   for performance.

## Write path architecture

```mermaid theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
%%{init: {"theme": "base", "themeVariables": {
  "background": "#ffffff", "primaryColor": "#ffffff", "primaryTextColor": "#221d19",
  "primaryBorderColor": "#ad9e95", "lineColor": "#6b625c", "textColor": "#221d19",
  "clusterBkg": "#f4ebe8", "clusterBorder": "#ad9e95", "edgeLabelBackground": "#ffffff",
  "fontFamily": "Inter, sans-serif", "fontSize": "18px"
}}}%%
graph TD
    subgraph "Client Network"
        C[Client App]
    end

    subgraph "Kubernetes Cluster"
        PL[Private Link<br/>Service]
        QN[Query Nodes<br/>Query planning + routing fleet]
        LA[Lance Agent]
        IP[Indexer Pods<br/>On-Demand]
    end

    subgraph "Messaging"
        EH[Message Queue<br/>Write Events]
    end

    subgraph "Storage"
        BS[Object<br/>Storage]
    end

    C -->|Private Connection| PL
    PL --> QN
    QN -->|Sync Write| BS
    QN -->|Async Events| EH
    EH -->|Consume| LA
    LA -->|Launch| IP
    IP -->|Index & Optimize| BS
    classDef default fill:#ffffff,stroke:#ad9e95,stroke-width:1px,color:#221d19
    classDef accent fill:#fff1ec,stroke:#e8582d,stroke-width:1.5px,color:#221d19
    class BS accent
```

### Write path flow

Query nodes write data and indices synchronously to object storage in Lance format while asynchronously sending
data modification events to the message queue (a managed service such as Azure EventHub, or a self-hosted Kafka
cluster). These write events are processed by the Lance Agent, which launches indexing pods or data optimization
pods to optimize data for better read performance.

## Deployment models

LanceDB Enterprise supports three deployment models, available on AWS, GCP, and Azure:

### 1. Fully managed service

* **Infrastructure and storage** in LanceDB's cloud account.
* **Complete management** by the LanceDB team.
* **Simplest setup** for customers.

### 2. BYOC (bring your own cloud)

* **Infrastructure and storage** in the customer's cloud account.
* **Fully managed by LanceDB.**
* **Full control** over data residency.

### 3. Hybrid -- bring your own container

* **Infrastructure** in LanceDB's account.
* **Storage containers** in the customer's account.

> [!NOTE]
>
> For private deployments, high performance at extreme scale, or if you have strict security requirements, [contact us about LanceDB Enterprise](https://www.lancedb.com/contact).

## Azure-specific: storage containers

The one part of this architecture that is genuinely cloud-specific is how object storage is organized. On Azure,
data lives in **Blob Storage containers**, grouped under one or more **storage accounts** -- the same multi-tenant
or multi-workload layout applies whether you use a single account with several containers, or split workloads
across accounts:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
%%{init: {"theme": "base", "themeVariables": {
  "background": "#ffffff", "primaryColor": "#ffffff", "primaryTextColor": "#221d19",
  "primaryBorderColor": "#ad9e95", "lineColor": "#6b625c", "textColor": "#221d19",
  "clusterBkg": "#f4ebe8", "clusterBorder": "#ad9e95", "edgeLabelBackground": "#ffffff",
  "fontFamily": "Inter, sans-serif", "fontSize": "18px"
}}}%%
graph TB
    subgraph "Multi-Account & Multi-Container Support"
        SA1[Storage Account 1]
        SA2[Storage Account 2]
        SA3[Storage Account N]

        SA1 --> C1A[Container A]
        SA1 --> C1B[Container B]
        SA1 --> C1C[Container C]

        SA2 --> C2A[Container X]
        SA2 --> C2B[Container Y]

        SA3 --> C3A[Container 1]
        SA3 --> C3B[Container 2]
    end
    classDef default fill:#ffffff,stroke:#ad9e95,stroke-width:1px,color:#221d19
```

The equivalent on other clouds is an S3 bucket (AWS) or a Cloud Storage bucket (GCP); everything else on this page
\-- the Kubernetes cluster layout, the read and write paths, and the deployment models -- applies unchanged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.