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

# Weaviate

> Deploy a Weaviate vector database cluster on Control Plane. Covers Raft-consensus clustering, AI module configuration for vectorization and generative search, authentication, and scheduled backups to S3 or GCS.

## Overview

Weaviate is an AI-native vector database designed for storing, indexing, and querying vector embeddings alongside structured object data. This template deploys a multi-node Weaviate 1.38 cluster using Raft consensus for schema and cluster state management, with optional AI module support for vectorization and generative search, and optional scheduled backups to AWS S3 or GCS.

### What Gets Created

* **Stateful Weaviate Workload** — A multi-replica cluster with one persistent volume per node for vector and object data.
* **Volume Set** — Persistent storage per replica with optional autoscaling.
* **Cron Backup Workload** *(optional)* — Triggers Weaviate's built-in backup API on a schedule to write full snapshots to cloud storage.
* **Identity & Policy** — An identity bound to the workload with `reveal` access to credential secrets, and cloud storage access when backup is enabled.
* **Secrets** — An opaque secret holding the API key, user, and all AI module API keys.

<Note>
  This template does not create a GVC. You must deploy it into an existing GVC.
</Note>

## Prerequisites

This template has no external prerequisites unless backup is enabled. To install, follow the instructions for your preferred method:

<CardGroup cols={2}>
  <Card title="UI" href="/template-catalog/install-manage/ui" icon="laptop">
    Browse, install, and manage templates visually
  </Card>

  <Card title="CLI" href="/template-catalog/install-manage/cli" icon="terminal">
    Manage templates from your terminal
  </Card>

  <Card title="Terraform" href="/template-catalog/install-manage/terraform" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><g fill-rule="evenodd"><path d="M77.941 44.5v36.836L46.324 62.918V26.082zm0 0" fill="#5c4ee5"/><path d="M81.41 81.336l31.633-18.418V26.082L81.41 44.5zm0 0" fill="#4040b2"/><path d="M11.242 42.36L42.86 60.776V23.941L11.242 5.523zm0 0M77.941 85.375L46.324 66.957v36.82l31.617 18.418zm0 0" fill="#5c4ee5"/></g></svg>}>
    Declare templates in your Terraform configurations
  </Card>

  <Card
    title="Pulumi"
    href="/template-catalog/install-manage/pulumi"
    icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" id="Pulumi-Icon--Streamline-Svg-Logos" height="24" width="24">
    <desc>
        Pulumi Icon Streamline Icon: https://streamlinehq.com
    </desc>
    <path fill="#f26e7e" d="M4.683025 13.3318c0.869125 -0.5018 0.870575 -2.1264 0.003225 -3.62865s-2.27504 -2.313275 -3.1441725 -1.811475C0.672945 8.3935 0.6715 10.0181 1.53885 11.52035c0.86735 1.502275 2.27505 2.313275 3.144175 1.81145Zm0.0052 3.2167c0.86735 1.502275 0.865925 3.126875 -0.003225 3.628675 -0.86915 0.5018 -2.2768275 -0.309225 -3.144175 -1.81145 -0.8673525 -1.50225 -0.8659075 -3.126875 0.003225 -3.628675 0.8691325 -0.5018 2.276825 0.309225 3.144175 1.81145Zm5.922875 3.4243c0.86735 1.50225 0.8659 3.126775 -0.003225 3.62875 -0.869125 0.501775 -2.27685 -0.309325 -3.1442 -1.81155 -0.867325 -1.50225 -0.865875 -3.12685 0.00325 -3.628675 0.869125 -0.5018 2.276825 0.309225 3.144175 1.811475Zm-0.001925 -6.845275c0.86735 1.50225 0.8659 3.12685 -0.003225 3.628675 -0.869125 0.5018 -2.276825 -0.309225 -3.144175 -1.811475 -0.86735 -1.50225 -0.8659 -3.12685 0.003225 -3.62865 0.869125 -0.501825 2.276825 0.3092 3.144175 1.81145Z" stroke-width="0.25"></path>
    <path fill="#8a3391" d="M22.45775 11.524125c0.86725 -1.502225 0.865925 -3.12685 -0.003225 -3.62865 -0.869125 -0.501825 -2.276825 0.3092 -3.144175 1.811475 -0.86735 1.50225 -0.8659 3.126825 0.003225 3.62865 0.869125 0.501825 2.276825 -0.3092 3.144175 -1.811475Zm0.000175 3.2151c0.869075 0.5018 0.870625 2.1264 0.003225 3.62865 -0.86735 1.50225 -2.27505 2.313275 -3.144175 1.81145 -0.869125 -0.5018 -0.870575 -2.126425 -0.003225 -3.62865 0.86735 -1.50225 2.27505 -2.313275 3.144175 -1.81145ZM16.536225 18.157875c0.86915 0.501825 0.8706 2.126425 0.00325 3.628675 -0.86735 1.502125 -2.275075 2.313225 -3.1442 1.81145 -0.869125 -0.50175 -0.870575 -2.126425 -0.003225 -3.62865 0.867375 -1.502275 2.27505 -2.3133 3.144175 -1.811475Zm-0.003325 -6.843775c0.869125 0.5018 0.870575 2.126425 0.003225 3.628675s-2.27505 2.313275 -3.1442 1.811475c-0.869125 -0.501825 -0.870575 -2.126425 -0.003225 -3.628675 0.86735 -1.502275 2.27505 -2.313275 3.1442 -1.811475Z" stroke-width="0.25"></path>
    <path fill="#f7bf2a" d="M15.138225 2.06721c0 1.003615 -1.40625 1.817215 -3.14095 1.817215 -1.7347 0 -3.14095 -0.8136 -3.14095 -1.817215C8.856325 1.06359 10.262575 0.25 11.997275 0.25c1.7347 0 3.14095 0.81359 3.14095 1.81721ZM9.2166 5.482375c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172s1.40625 -1.817225 3.14095 -1.817225c1.7347 0 3.14095 0.8136 3.14095 1.817225Zm8.71005 1.8172c1.7347 0 3.14095 -0.813575 3.14095 -1.8172s-1.40625 -1.817225 -3.14095 -1.817225c-1.7347 0 -3.14095 0.8136 -3.14095 1.817225s1.40625 1.8172 3.14095 1.8172Zm-2.788425 1.605625c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172 0 -1.0036 1.40625 -1.8172 3.14095 -1.8172 1.7347 0 3.14095 0.8136 3.14095 1.8172Z" stroke-width="0.25"></path>
    </svg>}
  >
    Declare templates in your Pulumi programs
  </Card>
</CardGroup>

## Configuration

The default `values.yaml` for this template:

```yaml theme={null}
replicas: 3

image: semitechnologies/weaviate:1.38.0

clusterName: my-weaviate

# IMPORTANT: Change all credentials before deploying to production
apiKey: changeme           # Bearer token for authenticating with Weaviate
apiUser: admin@example.com # Username associated with the API key

queryDefaultsLimit: 25

# Default vectorizer applied to new collections
# Options: none, text2vec-openai, text2vec-cohere, text2vec-huggingface, text2vec-aws
defaultVectorizerModule: none

modules:
  enabled: []
  # - generative-anthropic
  # - generative-openai
  # - generative-cohere
  # - text2vec-openai
  # - text2vec-cohere
  # - text2vec-huggingface

  openai:
    apiKey: ""
  anthropic:
    apiKey: ""
  cohere:
    apiKey: ""
  huggingface:
    apiKey: ""

cpu: 2
memory: 4Gi

volumes:
  data:
    initialCapacity: 20  # GiB
    autoscaling:
      maxCapacity: 200
      minFreePercentage: 20
      scalingFactor: 1.5

multiZone:
  enabled: false

internal_access:
  type: same-gvc  # Options: same-gvc, same-org, workload-list
  workloads:
    # - //gvc/GVC_NAME/workload/WORKLOAD_NAME

backup:
  enabled: false
  provider: aws   # options: aws or gcp
  schedule: "0 2 * * *"  # daily at 2am UTC

  resources:
    cpu: 250m
    memory: 256Mi

  aws:
    bucket: my-backup-bucket
    region: us-east-1
    cloudAccountName: my-s3-cloudaccount
    policyName: my-backup-policy
    path: weaviate/backups

  gcp:
    bucket: my-backup-bucket
    cloudAccountName: my-gcs-cloudaccount
    path: weaviate/backups
```

### Core Settings

* `replicas` — Number of Weaviate nodes. A minimum of 3 is recommended for production — the Raft consensus layer requires a quorum (2 of 3) to elect a leader and process schema changes.
* `clusterName` — Internal cluster identifier used in Raft coordination.
* `apiKey` — Bearer token that controls all access to the Weaviate instance, including schema management and data. **Change before deploying to production.**
* `apiUser` — Username associated with the API key, used for authorization and the admin list.
* `queryDefaultsLimit` — Default result limit applied to queries that do not specify one.
* `defaultVectorizerModule` — The vectorizer Weaviate calls automatically on insert and query for new collections. Set to `none` if you are providing your own vectors.
* `cpu` / `memory` — Resource limits applied to each Weaviate replica.

### Storage

* `volumes.data.initialCapacity` — Initial volume size in GiB per replica (minimum 10). Defaults to 20.
* `volumes.data.autoscaling.maxCapacity` — Maximum volume size in GiB when autoscaling is enabled.
* `volumes.data.autoscaling.minFreePercentage` — Percentage of free space that triggers a scale-up.
* `volumes.data.autoscaling.scalingFactor` — Multiplier applied to the current capacity when scaling up.

### Multi-Zone

Set `multiZone.enabled: true` to spread replicas across availability zones within the location. Verify your selected location supports multi-zone before enabling.

### Firewall

* `internal_access.type` — Controls which workloads can reach Weaviate:
  * `same-gvc` — All workloads in the same GVC (default).
  * `same-org` — All workloads in the org.
  * `workload-list` — Only workloads listed in `internal_access.workloads`.

## AI Modules

Weaviate supports pluggable AI modules for automatic vectorization and generative search. Modules are disabled by default.

<Warning>
  Adding an API key alone does not activate a module. Every module you intend to use must also be listed in `modules.enabled`.
</Warning>

### Supported Modules

| Module                 | Type       | Provider     | API Key Field                |
| ---------------------- | ---------- | ------------ | ---------------------------- |
| `text2vec-openai`      | Vectorizer | OpenAI       | `modules.openai.apiKey`      |
| `text2vec-cohere`      | Vectorizer | Cohere       | `modules.cohere.apiKey`      |
| `text2vec-huggingface` | Vectorizer | Hugging Face | `modules.huggingface.apiKey` |
| `generative-openai`    | Generative | OpenAI       | `modules.openai.apiKey`      |
| `generative-anthropic` | Generative | Anthropic    | `modules.anthropic.apiKey`   |
| `generative-cohere`    | Generative | Cohere       | `modules.cohere.apiKey`      |

### Example — Automatic Vectorization with OpenAI

```yaml theme={null}
defaultVectorizerModule: text2vec-openai

modules:
  enabled:
    - text2vec-openai
  openai:
    apiKey: "sk-..."
```

With this configuration, Weaviate automatically calls OpenAI's embedding API when objects are inserted and when vector searches are run — no client-side embedding step required.

### Example — Generative Search with Anthropic

```yaml theme={null}
modules:
  enabled:
    - generative-anthropic
  anthropic:
    apiKey: "sk-ant-..."
```

Enabling any module with an API key automatically adds outbound internet access to the Weaviate workload's firewall so it can reach the provider's API.

## Connecting

Weaviate is accessible internally from any workload in the same GVC:

| Access                      | Hostname                                       | Port                          |
| --------------------------- | ---------------------------------------------- | ----------------------------- |
| Load-balanced (any replica) | `{release-name}-weaviate.{gvc}.cpln.local`     | `8080` (REST), `50051` (gRPC) |
| Specific replica            | `{release-name}-weaviate-{n}.{gvc}.cpln.local` | `8080` (REST), `50051` (gRPC) |

Authenticate using the Bearer token set in `apiKey`:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
     http://{release-name}-weaviate.{gvc}.cpln.local:8080/v1/meta
```

## Backing Up

When enabled, a cron workload triggers Weaviate's built-in backup API on schedule to write a full snapshot to cloud storage. Each backup is stored at `{path}/{backup-id}/` and includes all collections and their data.

### AWS S3

<Steps>
  <Step title="Create a bucket">
    Create an S3 bucket. Set `backup.aws.bucket` and `backup.aws.region` to match.
  </Step>

  <Step title="Set up a Cloud Account">
    If you do not have one, [create a Cloud Account](https://docs.controlplane.com/guides/create-cloud-account). Set `backup.aws.cloudAccountName` to its name.
  </Step>

  <Step title="Create an IAM policy">
    Create an IAM policy with the following JSON (replace `YOUR_BUCKET_NAME`) and set `backup.aws.policyName` to its name:

    ```json theme={null}
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "s3:GetObject",
                    "s3:PutObject",
                    "s3:DeleteObject",
                    "s3:ListBucket",
                    "s3:GetObjectVersion",
                    "s3:DeleteObjectVersion"
                ],
                "Resource": [
                    "arn:aws:s3:::YOUR_BUCKET_NAME",
                    "arn:aws:s3:::YOUR_BUCKET_NAME/*"
                ]
            }
        ]
    }
    ```
  </Step>
</Steps>

### GCS

<Steps>
  <Step title="Create a bucket">
    Create a GCS bucket. Set `backup.gcp.bucket` to its name.
  </Step>

  <Step title="Set up a Cloud Account">
    If you do not have one, [create a Cloud Account](https://docs.controlplane.com/guides/create-cloud-account). Set `backup.gcp.cloudAccountName` to its name.
  </Step>
</Steps>

<Warning>
  You must add the `Storage Admin` role to the GCP service account created for the Cloud Account.
</Warning>

## Restoring a Backup

Exec into any Weaviate replica and POST to the restore endpoint. Replace `s3` with `gcs` for GCP backups, and `BACKUP_ID` with the backup name from your bucket (e.g. `weaviate-backup-20260610-020000`):

```bash theme={null}
# Trigger restore
wget -qO- \
  --header='Authorization: Bearer YOUR_API_KEY' \
  --header='Content-Type: application/json' \
  --post-data='{}' \
  'http://localhost:8080/v1/backups/s3/BACKUP_ID/restore'

# Poll for completion
wget -qO- \
  --header='Authorization: Bearer YOUR_API_KEY' \
  'http://localhost:8080/v1/backups/s3/BACKUP_ID/restore'
```

<Warning>
  Restore will fail if a collection from the backup already exists on the cluster. Drop existing collections first or restore to a fresh deployment.
</Warning>

## Important Notes

* **Minimum 3 replicas for production** — Raft requires a quorum (2 of 3) to elect a leader and process schema changes. A 2-node cluster cannot reach quorum if one node fails.
* **API key security** — Change `apiKey` before deploying to production. This key controls all access to the instance including schema management and data.
* **Modules must be declared** — Adding an API key alone does not activate a module. Every module you intend to use must be listed in `modules.enabled`.
* **Multi-zone** — Verify your selected location supports multi-zone before enabling.

## External References

<CardGroup cols={2}>
  <Card title="Weaviate Documentation" href="https://weaviate.io/developers/weaviate" icon="book">
    Official Weaviate documentation
  </Card>

  <Card title="Weaviate REST API" href="https://weaviate.io/developers/weaviate/api/rest" icon="code">
    REST API reference including backup and restore endpoints
  </Card>

  <Card title="Weaviate Modules" href="https://weaviate.io/developers/weaviate/modules" icon="puzzle-piece">
    Documentation for vectorizer and generative AI modules
  </Card>

  <Card title="Weaviate GraphQL API" href="https://weaviate.io/developers/weaviate/api/graphql" icon="brackets-curly">
    GraphQL API reference for querying vector and object data
  </Card>
</CardGroup>