Skip to main content

Overview

Weaviate is an AI-native vector database for storing, indexing, and querying vector embeddings alongside structured object data. This template deploys a Weaviate 1.38 cluster of replicas nodes in a single location, using Raft consensus for schema and cluster state, with one persistent volume per node, optional AI provider modules, and optional scheduled backups to AWS S3 or GCS. The cluster has no public endpoint by design — it is reachable only from inside Control Plane, scoped by internalAccess.type. The Weaviate API key and every AI provider key are secrets you create before installing; none of them pass through Helm or land in the release.
This template does not create a GVC. It deploys into an existing GVC that you already have.

What Gets Created

Prerequisites

One secret must exist before you install. It holds the API key every client authenticates with. Secrets are org-level, so no GVC flag is involved.
1

Create the API key secret

An opaque secret whose entire payload is the API key. --encoding plain is required:
Set apiKeySecretName to the name you used, and set apiUser to the username the key maps to. Weaviate has no anonymous access in this template.
2

Read the key back later

Keep your own copy of the key — the platform is the only place it is stored. Pass -o yaml; a bare cpln secret reveal prints only a summary table:
3

Create AI provider secrets (optional)

Only needed if you want Weaviate to call a provider for embeddings or generative search. Create one opaque secret per provider, holding just that provider’s key:
Set modules.openai.apiKeySecretName (or the anthropic, cohere, huggingface equivalent) to that name. Leaving a provider’s apiKeySecretName empty means the provider is genuinely off: no environment variable, no reveal grant, and no outbound internet access on the workload.
Create the API key secret before installing, or the deployment wedges silently. A name that points at a secret which does not exist installs “successfully” and then never starts. The container never runs, so cpln logs returns zero lines, and every summary surface just looks like a slow deploy. The one place the reason appears is status.versions[].message:
Use get-deployments — plain cpln workload get has no versions key. Creating the missing secret repairs the deployment on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-weaviate --gvc GVC_NAME to skip the wait.
Naming a provider secret gives you a live, billable integration. It is not inert configuration held in reserve, and modules.enabled does not gate it — see AI Modules. Only supply a provider key when you intend that provider to be used.
Backups need a bucket and a Control Plane Cloud Account before they can be enabled — see Backing Up. Nothing else is required.

Installation

Install from the marketplace registry into an existing GVC, pointing apiKeySecretName at the secret you created:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Each subsection shows the shipped defaults for one area of values.yaml.

Cluster

Three replicas is the practical minimum for Raft, which needs a quorum (2 of 3) to elect a leader and accept schema changes. A single-replica install (replicas: 1) has no cluster membership to maintain. Read Scaling and Availability before running a multi-replica cluster in production.

Authentication

The key is read straight from your secret into Weaviate’s allowed-keys setting and never appears in the Helm release or the rendered manifest. Anonymous access is disabled unconditionally; a request without the exact key returns 401 Unauthorized.

Query Behavior

Leave defaultVectorizerModule: none when your application supplies its own vectors. Set it to a provider module to have Weaviate call that provider’s embedding API on insert and query.

AI Modules

Supplying a provider key is what activates a provider, not modules.enabled. On Weaviate 1.38 the API-based vectorizer and generative modules load whether or not they are listed, so a collection that names a vectorizer such as text2vec-openai will call that provider as soon as its key is present — and bill you for it. Only name a provider secret when you intend that provider to be used, and clear the name when you stop using it.
modules.enabled is written to Weaviate’s ENABLE_MODULES setting. When backups are enabled the template appends backup-s3 or backup-gcs to it for you. Naming any provider secret, or enabling backups, opens outbound internet access on the Weaviate workload so it can reach that API; with neither, the workload has no egress at all.

Resources

Memory is the sizing constraint, not CPU. An undersized cluster fails with out-of-memory restarts rather than slow queries.

Storage

Volume data survives a redeploy and an upgrade. Uninstalling the release deletes the volume set.

Placement

Access

Weaviate is reachable only from inside Control Plane — this template opens no public endpoint, and that is not configurable. A change to internalAccess takes up to a couple of minutes to take effect.

Backup

The bucket, Cloud Account and IAM steps are under Backing Up.

Connecting

Weaviate is reachable from workloads inside Control Plane, subject to internalAccess.type. Authenticate every request with the API key as a bearer token. From another workload in the GVC:
From your own machine, open a tunnel and call the same endpoint on localhost:
The workload is assigned a canonical *.cpln.app hostname like any other, but every request from the internet is refused at the platform edge with 403 RBAC: access denied — a valid API key does not help, because the request never reaches Weaviate. If you need browser or off-platform access, put your own authenticating proxy in front of it inside the GVC, or use cpln port-forward.

Operations

Backing Up

With backup.enabled: true, the RELEASE_NAME-weaviate-backup cron workload calls Weaviate’s backup API on backup.schedule and writes a full snapshot of every collection to {path}/{backup-id}/ in your bucket. Backup IDs are written as weaviate-backup-YYYYMMDD-HHMMSS.
The backup path has not been exercised end to end from this template. Rendering and the chart’s validation of the backup settings are checked, but no snapshot has been written to S3 or GCS by this template. Run one on your own bucket and confirm the objects land before you rely on the schedule. A misconfigured cloud binding can report a successful install while the identity is unusable, so check the objects, not the install.
With internalAccess.type: workload-list, the backup job is denied. The cron job is a separate workload and the template does not add it to the allow-list, so its calls to Weaviate are refused like any other unlisted workload. Add //gvc/GVC_NAME/workload/RELEASE_NAME-weaviate-backup to internalAccess.workloads yourself, or use same-gvc or same-org.

AWS S3

1

Create a bucket

Create an S3 bucket. Set backup.aws.bucket and backup.aws.region to match, and backup.aws.path to the prefix you want snapshots written under.
2

Set up a Cloud Account

If you do not have one, create a Cloud Account for the AWS account holding the bucket. Set backup.aws.cloudAccountName to its name.
3

Create an IAM policy

Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME, and set backup.aws.policyName to its name. The identity carries cpln-connector and this bucket-scoped policy only:

GCS

1

Create a bucket

Create a GCS bucket. Set backup.gcp.bucket to its name and backup.gcp.path to the prefix.
2

Set up a Cloud Account

If you do not have one, create a Cloud Account for the GCP project. Set backup.gcp.cloudAccountName to its name.
3

Grant the bucket role

Grant the Cloud Account’s service account roles/storage.objectAdmin on that bucket. The template requests exactly that role on exactly that bucket, and nothing more.
To check the outcome of a scheduled run, read the backup job’s logs:

Restoring a Backup

This restore procedure is unverified for this template. It follows the upstream Weaviate backup API and the backup module configuration this chart ships, and the pinned image provides wget, but it has not been run against a snapshot written by this template. Test it against a backup you do not need before you depend on it.
Run the restore from inside any Weaviate replica. Use gcs in place of s3 for GCP backups, and replace BACKUP_ID with the backup name from your bucket:
Poll the same URL without --post-data until the status reads SUCCESS:
A restore is not a merge: it fails if a collection from the backup already exists on the cluster. Drop the collection first, or restore into a fresh release.

Upgrading From 1.0.1 or Earlier

Template version 1.1.0 is a security release. Every credential the chart used to accept as a value is now a secret you create and reference by name, and carrying a 1.0.1 values file forward fails at render with a message naming its replacement — nothing silently falls back to a default.
Treat the key on any 1.0.1 or earlier install as compromised. Those versions shipped a working API key as a values default, published in the public template repository and shared by every install that did not override it. It is the only authentication Weaviate has, so anyone holding it can read and write every collection. Rotate it rather than simply upgrading.
The render guard for the API key reads:
1

Rotate the key, do not carry it forward

Generate a new key and create the secret as shown in Prerequisites. If you overrode the old default with your own value, that value still travelled in the Helm release and is worth rotating too.
2

Replace the removed keys

Delete apiKey, clusterName, and any modules.{provider}.apiKey entries from your values. Set apiKeySecretName, rename internal_access to internalAccess, and create a provider secret for each provider you actually use.
3

Update every client

The API key changes, so every application, notebook, and client library holding the old bearer token must be updated.
4

Plan the restart

A cpln helm upgrade restarts the cluster one replica at a time. Read Scaling and Availability first and verify cluster health afterwards — the platform’s ready status will not tell you if a node failed to rejoin.

Upgrading From 1.1.0

Template version 1.1.1 removes the aws::ReadOnlyAccess managed policy from the backup identity. That policy granted read access to every bucket in your AWS account and contains no write actions, so it was never carrying the backup itself — but it was silently supplying any read action your own bucket-scoped policy happened to omit. If you back up to S3, update your IAM policy to the full action list under AWS S3 before upgrading. If it already matches, no action is needed. GCS backups and installs without backups are unaffected. Nothing else changes.

Scaling and Availability

replicas sets the number of Weaviate nodes, each with its own volume. Raft needs a quorum to elect a leader and accept schema changes, so a three-node cluster tolerates the loss of one node and a two-node cluster tolerates none. Upgrades restart replicas one at a time.
A replica can fail to rejoin the cluster after a rolling restart, and the platform will not tell you. The readiness probe only checks that the HTTP server is up, so a node that came back without rejoining the Raft cluster still reports ready and still receives traffic. Clients then see intermittent 404 Not Found for collections that exist on the other nodes. Verify cluster health after any restart — an upgrade, an image bump, or a platform reschedule — instead of trusting the ready status.
Check membership from inside a replica. A healthy cluster reports one Leader and the remaining nodes as Follower, and /v1/nodes lists every replica as HEALTHY:
A split node reports "state":"Candidate" with an empty leaderId, and /v1/nodes queried from a healthy replica lists fewer nodes than you deployed. No in-place repair for a split node has been verified for this template. A single-replica install (replicas: 1) has no Raft membership to lose and is not exposed to this.

Troubleshooting

Symptom: cpln helm install succeeds, every resource exists, but RELEASE_NAME-weaviate never reaches ready and cpln logs prints zero lines.Cause: The secret named by apiKeySecretName (or a provider’s apiKeySecretName) does not exist. The container is never started, so there is nothing to log. The only diagnostic is status.versions[].message:
Fix: Create the missing secret as shown in Prerequisites. The deployment recovers on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-weaviate --gvc GVC_NAME to skip the wait.
Symptom: Requests return 401 Unauthorized even with the Authorization: Bearer header set.Cause: The key you are sending is not the current payload of the secret named by apiKeySecretName, or you rotated the secret without restarting the cluster — a secret is read when a replica starts, and nothing re-reads it while the replica lives.Fix: Read the key the cluster trusts with cpln secret reveal SECRET_NAME -o yaml. After changing the secret’s payload, force a redeployment so every replica picks up the new key:
Symptom: After an upgrade or restart, roughly one request in replicas fails with 404 Not Found for a collection other requests find, while every replica reports ready.Cause: One replica did not rejoin the Raft cluster after its restart and is serving an empty schema. It still passes the readiness probe, so it stays in rotation.Fix: Identify the node with the /v1/cluster/statistics and /v1/nodes checks under Scaling and Availability. No in-place repair has been verified for this template; keep a current backup so you can restore into a fresh release.
Symptom: Inserts into a collection whose vectorizer is a provider module (for example text2vec-openai) produce embeddings and provider charges, even though modules.enabled: [].Cause: On Weaviate 1.38 the API-based modules load regardless of modules.enabled. Naming a provider’s apiKeySecretName is what makes that provider live.Fix: Set the provider’s apiKeySecretName back to "" and run cpln helm upgrade. That removes the environment variable, the reveal grant and the outbound internet access together.
Symptom: With internalAccess.type: workload-list, the RELEASE_NAME-weaviate-backup job’s calls to the cluster are refused and no snapshot is written.Cause: The backup job is a separate workload and is not on the allow-list.Fix: Add //gvc/GVC_NAME/workload/RELEASE_NAME-weaviate-backup to internalAccess.workloads, or use same-gvc or same-org.
Symptom: You changed internalAccess.type or internalAccess.workloads, upgraded, and a caller still gets 503 upstream connect error or a connection refusal.Cause: An access change takes up to a couple of minutes to take effect, and a denial is indistinguishable from an unhealthy upstream.Fix: Wait a couple of minutes and retry before concluding the setting did not apply.
Symptom: A request to the workload’s *.cpln.app hostname returns 403 RBAC: access denied even with a valid API key.Cause: This template closes inbound internet access unconditionally; the request is refused at the platform edge before it reaches Weaviate.Fix: Reach Weaviate from inside the GVC, through cpln port-forward, or through your own authenticating proxy deployed in the GVC. There is no values key to open the public endpoint.

Important Notes

  • Create the API key secret before you install. Without it the install reports success and the deployment silently wedges, with no container and no logs. See Prerequisites.
  • Verify cluster health after every restart. A replica that fails to rejoin the Raft cluster still reports ready and still receives traffic. See Scaling and Availability.
  • A named provider secret is a live, billable integration, whether or not the module is listed in modules.enabled.
  • Rotating the API key requires a forced redeployment. Update the secret’s payload, then run cpln workload force-redeployment RELEASE_NAME-weaviate --gvc GVC_NAME; until then the old key keeps working and the new one does not.
  • Keep your own copy of the API key. Losing it locks you out of every collection.
  • There is no public endpoint, and that is not configurable in this template. Reachability is internalAccess only, and an access change takes up to a couple of minutes to settle.
  • Size memory, not CPU. Vector indexes are RAM-resident; an undersized cluster fails with out-of-memory restarts.
  • Backups and restores are unverified from this template. Confirm a snapshot lands in your bucket, and test a restore, before depending on either.

External References

Weaviate Documentation

Official Weaviate documentation

REST API Reference

REST API reference, including the backup and restore endpoints

Modules

Vectorizer and generative module configuration

Authentication and Authorization

How Weaviate API key authentication and the admin list work

Backups

Upstream documentation for the backup and restore API

Weaviate Template

View the source files, default values, and chart definition