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 ofreplicas 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.
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.Create the API key secret
--encoding plain is required:apiKeySecretName to the name you used, and set apiUser to the username the key maps to. Weaviate has no anonymous access in this template.Read the key back later
-o yaml; a bare cpln secret reveal prints only a summary table:Create AI provider secrets (optional)
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.Installation
Install from the marketplace registry into an existing GVC, pointingapiKeySecretName at the secret you created:
UI
CLI
Terraform
Pulumi
Configuration
Each subsection shows the shipped defaults for one area ofvalues.yaml.
Cluster
replicas: 1) has no cluster membership to maintain. Read Scaling and Availability before running a multi-replica cluster in production.
Authentication
401 Unauthorized.
Query Behavior
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
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
Storage
Placement
Access
internalAccess takes up to a couple of minutes to take effect.
Backup
Connecting
Weaviate is reachable from workloads inside Control Plane, subject tointernalAccess.type. Authenticate every request with the API key as a bearer token.
*.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
Withbackup.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.
AWS S3
Create a bucket
backup.aws.bucket and backup.aws.region to match, and backup.aws.path to the prefix you want snapshots written under.Set up a Cloud Account
backup.aws.cloudAccountName to its name.Create an IAM policy
YOUR_BUCKET_NAME, and set backup.aws.policyName to its name. The identity carries cpln-connector and this bucket-scoped policy only:GCS
Create a bucket
backup.gcp.bucket to its name and backup.gcp.path to the prefix.Set up a Cloud Account
backup.gcp.cloudAccountName to its name.Grant the bucket role
roles/storage.objectAdmin on that bucket. The template requests exactly that role on exactly that bucket, and nothing more.Restoring a Backup
Run the restore from inside any Weaviate replica. Usegcs in place of s3 for GCP backups, and replace BACKUP_ID with the backup name from your bucket:
--post-data until the status reads SUCCESS:
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.Rotate the key, do not carry it forward
Replace the removed keys
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.Update every client
Plan the restart
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 theaws::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.
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:
"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
Workload never becomes ready and cpln logs returns nothing
Workload never becomes ready and cpln logs returns nothing
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:cpln workload force-redeployment RELEASE_NAME-weaviate --gvc GVC_NAME to skip the wait.Some requests return 404 Not Found for a collection that exists
Some requests return 404 Not Found for a collection that exists
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.A provider is being called and billed although modules.enabled is empty
A provider is being called and billed although modules.enabled is empty
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.Backup job fails to reach Weaviate with internalAccess.type workload-list
Backup job fails to reach Weaviate with internalAccess.type workload-list
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.A workload is still refused after changing internalAccess
A workload is still refused after changing internalAccess
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.403 RBAC access denied on the canonical cpln.app endpoint
403 RBAC access denied on the canonical cpln.app endpoint
*.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
internalAccessonly, 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.