pgvector

Overview

pgvector adds a vector column type and approximate nearest-neighbor indexes to PostgreSQL, so embeddings live in the same database as the relational data they describe. This template deploys one PostgreSQL 18 server with pgvector 0.8.6 on a persistent volume, an optional PgBouncer connection pooler in front of it, and an optional cron job that writes compressed pg_dumpall backups to AWS S3, Google Cloud Storage or a MinIO (S3-compatible) bucket. The extension is not just installed in the image — the template creates it on first boot, in the database named in your credentials secret. A fresh install can store vectors and run similarity queries with no setup SQL. Database credentials are not template values. The server reads its username, password and database name from a dictionary secret you create before installing, so no password passes through Helm or lands in the release. The template creates no credential secret of its own.

This template deploys into an existing GVC that you already have. It does not create or manage a GVC.

This is a single server, not a cluster — there is no replication or failover. For an automatically failing-over cluster use PostgreSQL Highly Available, whose image also carries pgvector; see Scaling and Availability for the version difference.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-pgvector`	PostgreSQL 18 with pgvector 0.8.6 (stateful, 1 replica, TCP `5432`)	—
Volume Set	`RELEASE_NAME-pgvector-vs`	`PGDATA` on an `ext4` general-purpose SSD volume; a final snapshot is kept for 7 days when the volume is deleted	—
Secret	`RELEASE_NAME-pgvector-init`	First-boot SQL mounted at `/docker-entrypoint-initdb.d/00-pgvector.sql`; holds the `CREATE EXTENSION` statements and no credentials	—
Identity	`RELEASE_NAME-pgvector-identity`	Shared by the database, pooler and backup workloads; carries the cloud account binding when backups use AWS or GCP	—
Policy	`RELEASE_NAME-pgvector-policy`	Grants the identity `reveal` on your credentials secret, the first-boot SQL secret and, for MinIO backups, the MinIO credentials secret — nothing else	—
Workload	`RELEASE_NAME-pgbouncer`	PgBouncer connection pooler (serverless, TCP `5432`)	`pgbouncer.enabled: true`
Workload	`RELEASE_NAME-pgvector-backup`	Scheduled `pg_dumpall` to S3, GCS or MinIO (cron)	`backup.enabled: true`

Prerequisites

One secret must exist before you install. It holds the credentials your applications put in their connection strings. Secrets are org-level, so no GVC flag is involved.

Create the database credentials secret

A dictionary secret holding exactly three keys — username, password and database. PostgreSQL creates that user (as a superuser) and that database the first time the volume is initialized, and the template creates the vector extension inside it:

cpln secret create-dictionary --name SECRET_NAME \
  --entry username=pgvector \
  --entry password='YOUR-STRONG-PASSWORD' \
  --entry database=vectors

Set config.credentialsSecretName to this name. Read it back later with cpln secret reveal SECRET_NAME -o yaml — a bare cpln secret reveal prints only a summary table, not the values.

Create the secret before installing, or the deployment wedges silently. The template refuses to render when config.credentialsSecretName is blank, but 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. The one place the reason appears is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-pgvector --gvc GVC_NAME -o yaml

The secret SECRET_NAME no longer exists. Workload updates are paused until the
secret is added or the reference to the secret removed.

Use get-deployments — plain cpln workload get has no versions key. Creating the missing secret repairs the deployment on its own within several minutes, or run cpln workload force-redeployment RELEASE_NAME-pgvector --gvc GVC_NAME to skip the wait. First boot then runs normally and the vector extension is created.

Backups are optional and need a bucket plus, for AWS or GCP, a Control Plane cloud account — see Backing Up. MinIO backups need a second dictionary secret holding accessKey and secretKey. Nothing else is required for a default install.

Installation

Install the chart from the marketplace registry, pointing it at the secret you created:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/pgvector \
  --version 1.0.0 --gvc GVC_NAME \
  --set config.credentialsSecretName=SECRET_NAME

Or follow the instructions for your preferred method:

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 block below is the shipped default for that part of values.yaml.

Server and Resources

image: pgvector/pgvector:0.8.6-pg18 # PostgreSQL 18 + pgvector 0.8.6 (Debian bookworm base)

resources:
  minCpu: 300m
  minMemory: 512Mi
  maxCpu: 1000m     # vector search is CPU-bound; keep maxCpu:minCpu at or below 4:1 or the apply is rejected
  maxMemory: 2048Mi # HNSW index builds are far faster when the graph fits in memory

On a stateful workload the ratio of maxCpu to minCpu may not exceed 4:1. Raising maxCpu without raising minCpu can cross that limit and is rejected when the workload is applied.

Credentials and Extensions

config:
  # REQUIRED PREREQUISITE SECRET — CREATE IT BEFORE YOU INSTALL.
  # A `dictionary` secret holding exactly three keys: `username`, `password`
  # and `database`. If it does not exist at install time the deployment
  # WEDGES silently — `cpln logs` returns nothing at all. See Prerequisites
  # in the README for the exact `cpln secret create-dictionary` command.
  credentialsSecretName: my-pgvector-credentials

  # Extra extensions created alongside `vector`, FIRST BOOT ONLY (ignored on an
  # existing volume). Must already exist in the image, e.g. pg_trgm, pgcrypto,
  # btree_gin. An unknown name fails the first boot — see the README.
  extraExtensions: []

The three credential keys are applied only when the volume is first initialized. Changing the secret afterwards does not change the stored password — see Rotating the Password. config.extraExtensions lists additional extensions to create alongside vector at first boot, such as pg_trgm, pgcrypto or btree_gin. Each entry must be an extension the image already ships and must match ^[a-z][a-z0-9_]*$; anything else is refused when the chart renders. The vector extension is always created and does not need to be listed.

A name the image does not carry costs you that extension. The first-boot script stops at the bad name, the container exits once, and the restart finds a populated data directory and skips initialization — leaving a healthy server that has vector (created first) but not your extra extension, with nothing in the deployment status to say so. Adding an extension later is one statement:

CREATE EXTENSION IF NOT EXISTS pg_trgm;

Storage

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false # Set to true to enable autoscaling
    maxCapacity: 100 # Maximum capacity in GiB when autoscaling is enabled
    minFreePercentage: 10 # Minimum free percentage to trigger scaling when autoscaling is enabled
    scalingFactor: 1.2 # Scaling factor to determine how much to scale up when autoscaling is triggered

Internal Access

internalAccess: # Sets the internal firewall scope - if set to none, nothing in the GVC can reach the database
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads:  # Note: can only be used if type is same-gvc or workload-list
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

Type	Who can reach port `5432`
`none`	No workload
`same-gvc`	Every workload in the same GVC
`same-org`	Every workload in the same org
`workload-list`	Only the workloads listed in `internalAccess.workloads`

The same setting applies to the PgBouncer workload when it is enabled. A change to internalAccess can take several minutes to take effect — re-test before concluding it did not apply.

Public Access

publicAccess:
  enabled: false # exposes 5432 via a TCP load balancer; connections are unencrypted — prefer internal access

When enabled, Control Plane assigns a canonical endpoint. Read it from status.canonicalEndpoint:

cpln workload get RELEASE_NAME-pgvector --gvc GVC_NAME -o yaml

Public connections are unencrypted. The image ships no TLS certificate, so a client that demands sslmode=require cannot connect; the libpq default of sslmode=prefer falls back to plaintext. Anyone who reaches the endpoint needs only the database password, so prefer internal access over RELEASE_NAME-pgvector.GVC_NAME.cpln.local where you can. A change to publicAccess can take several minutes to take effect.

PgBouncer

PgBouncer multiplexes many application connections into a small pool of real database connections — the bursty, short-lived connections typical of retrieval and embedding services. When enabled it becomes the endpoint your applications connect to, and it reads the same credentials secret and identity as the server — nothing extra to configure.

pgbouncer:
  enabled: false
  image: edoburu/pgbouncer:v1.25.1-p0
  poolMode: transaction # session, transaction, statement; in transaction mode session GUCs LEAK between clients
  defaultPoolSize: 25   # number of real Postgres connections PgBouncer maintains
  maxClientConn: 1000   # maximum number of client connections PgBouncer accepts
  replicas: 1

  resources:
    cpu: 200m
    memory: 128Mi

`poolMode`	Behaviour
`transaction`	The server connection is held for one transaction. Best for most web and API workloads; not compatible with plain `SET` variables, temporary tables or advisory locks.
`session`	Held for the whole client session. Compatible with everything, less reuse — raise `defaultPoolSize` to your expected concurrency.
`statement`	Returned after every statement. Transactions are not supported.

In transaction mode a plain SET hnsw.ef_search is not bound to your client — it can leak between clients. PgBouncer hands the same server connection to different clients, so your setting may be lost, may be replaced by another client’s value, or may raise ERROR: unrecognized configuration parameter "hnsw.ef_search". It matters on this template because ef_search is the recall knob. Either scope the setting to a transaction with SET LOCAL (see Using pgvector), or set pgbouncer.poolMode: session at the cost of connection multiplexing. This is upstream PgBouncer behaviour; PgBouncer is off by default, so a default install is not exposed to it.

Backup

A cron workload runs pg_dumpall on the schedule and uploads a gzip-compressed SQL dump of every database and role to the bucket for the chosen provider. It authenticates with the username and password from your credentials secret. Each provider’s bucket, cloud account and policy steps are under Backing Up.

backup:
  enabled: false
  image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0 # PG18 client, matches the server major
  schedule: "0 2 * * *"   # daily at 2am UTC

  resources:
    cpu: 100m
    memory: 128Mi

  provider: aws # Options: aws, gcp, or minio

  aws:
    bucket: my-pgvector-bucket
    region: us-east-1
    cloudAccountName: my-s3-cloud-account
    policyName: my-pgvector-backup-policy # bucket-scoped IAM policy, see README
    prefix: pgvector/backups # folder name where your backups will be stored

  gcp:
    bucket: my-pgvector-bucket
    cloudAccountName: my-gcs-cloud-account
    prefix: pgvector/backups # folder name where your backups will be stored

  minio: # Backup to a self-hosted MinIO workload (or any S3-compatible endpoint)
    endpoint: http://my-minio-workload:9000 # e.g. http://WORKLOAD_NAME:9000 for an internal MinIO template deployment
    bucket: my-pgvector-bucket
    # REQUIRED PREREQUISITE SECRET when provider is `minio` — a `dictionary`
    # secret holding `accessKey` and `secretKey`. See Storage setup in the README.
    credentialsSecretName: my-pgvector-minio-credentials
    prefix: pgvector/backups # folder name where your backups will be stored

Changing backup.provider on an existing release leaves the old cloud binding attached. Control Plane merges an identity’s cloud-binding block and never removes one, so a release switched from aws to gcp keeps both bindings even though the template renders only the new one. Uninstall and reinstall to change providers cleanly.

Connecting

Everything below is reachable from inside the GVC, subject to internalAccess.type; the public path exists only when publicAccess.enabled: true.

What	Address	Notes
PostgreSQL, direct	`RELEASE_NAME-pgvector.GVC_NAME.cpln.local:5432`	Always available.
PostgreSQL, pooled	`RELEASE_NAME-pgbouncer.GVC_NAME.cpln.local:5432`	Only when `pgbouncer.enabled: true`. Prefer it when the pooler is on.
PostgreSQL, public	`status.canonicalEndpoint` on the `RELEASE_NAME-pgvector` workload, port `5432`	Only when `publicAccess.enabled: true`. Unencrypted.
Credentials	`cpln secret reveal SECRET_NAME -o yaml`	The `username`, `password` and `database` keys. Never stored in the Helm release.

To verify from your own machine, tunnel to the server and confirm the extension is present:

cpln port-forward RELEASE_NAME-pgvector 5432:5432 --gvc GVC_NAME

psql "postgresql://USERNAME:PASSWORD@127.0.0.1:5432/DATABASE" -c "select extversion from pg_extension where extname = 'vector'"

Or run psql inside the container, where the credentials are already present as environment variables:

cpln workload exec RELEASE_NAME-pgvector --gvc GVC_NAME --container pgvector -- psql -U USERNAME -d DATABASE -c "select extversion from pg_extension where extname = 'vector'"

Using pgvector

The vector extension is already created in the database named in your credentials secret, so there is no setup SQL to run:

CREATE TABLE items (id bigserial PRIMARY KEY, content text, embedding vector(1536));
CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);
SELECT id, content FROM items ORDER BY embedding <=> '[0.1,0.2,...]' LIMIT 5;

Operator	Distance	Index operator class
`<->`	L2 (Euclidean)	`vector_l2_ops`
`<=>`	Cosine	`vector_cosine_ops`
`<#>`	Negative inner product	`vector_ip_ops`
`<+>`	L1 (taxicab)	`vector_l1_ops`

Both index types are available; the planner chooses them on cost.

Index	Characteristics	Recall knob
`hnsw`	Graph built incrementally; slower to build, better recall per query	`SET hnsw.ef_search = 100;` (default `40`)
`ivfflat`	Wants representative data present at build time, and a list count: `WITH (lists = 100)`	`SET ivfflat.probes = 10;` (default `1`)

Approximate indexes trade recall for speed, so an exact match can be missed at the default settings — raise the recall knob when results look incomplete. Large index builds are much faster when the graph fits in maintenance_work_mem, for example SET maintenance_work_mem = '512MB'; within the resources.maxMemory you have given the server. With PgBouncer in transaction mode, set these per query inside a transaction so the setting cannot leak to another client:

BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT id FROM items ORDER BY embedding <=> '[0.1,0.2,...]' LIMIT 5;
COMMIT;

A vector column holds up to 16,000 dimensions but can only be indexed up to 2,000 — 1,536-dimension embeddings index fine, while 3,072-dimension ones are rejected with column cannot have more than 2000 dimensions for hnsw index. Use halfvec, which indexes up to 4,000 dimensions, or reduce the dimensionality.

Operations

Backing Up

Backups are off by default. Enable them with backup.enabled: true, pick a backup.provider, and complete that provider’s setup below first. The job writes postgres-TIMESTAMP.sql.gz objects under backup.PROVIDER.prefix in your bucket on every run of backup.schedule.

Backup Prerequisites

Complete the steps for your provider before enabling backups.

AWS S3

Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.
If you do not have one yet, create a Control Plane cloud account for the AWS account holding the bucket. Set backup.aws.cloudAccountName to its name.
Create an IAM policy scoped to exactly that bucket, replacing YOUR_BUCKET_NAME:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion",
                "s3:GetBucketLocation",
                "s3:AbortMultipartUpload",
                "s3:ListBucketMultipartUploads",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

Set backup.aws.policyName to that policy’s name. The template attaches it to the workload identity and nothing else — the bucket in your policy is the only storage the backup job can reach.

GCS

Create a GCS bucket. Set backup.gcp.bucket to its name.
Create a Control Plane cloud account for the GCP project holding the bucket, and set backup.gcp.cloudAccountName to its name.
Grant the cloud account’s service account the Storage Admin (roles/storage.admin) role. The template additionally binds the identity to roles/storage.objectAdmin on exactly the bucket in backup.gcp.bucket.

MinIO

No cloud account is needed — the job authenticates with a second prerequisite secret.

Create the bucket in MinIO. Set backup.minio.bucket to its name.
Set backup.minio.endpoint to the S3 API address including the port. For the MinIO template deployed in the same GVC that is http://WORKLOAD_NAME.GVC_NAME.cpln.local:9000.
Create a dictionary secret holding exactly the keys accessKey and secretKey, and set backup.minio.credentialsSecretName to its name. For the MinIO template these are its admin username and password:

cpln secret create-dictionary --name SECRET_NAME \
  --entry accessKey=MINIO_ACCESS_KEY \
  --entry secretKey=MINIO_SECRET_KEY

The policy this template creates grants the identity reveal on this secret as well as the database credentials secret and the first-boot SQL secret, and on nothing else.

Restoring a Backup

Each backup is a gzip-compressed pg_dumpall script, so it is restored by connecting to the postgres maintenance database as the superuser from your credentials secret; the script recreates the roles and databases it contains. Because the dump includes CREATE EXTENSION IF NOT EXISTS vector, restore into a server whose image carries pgvector — a fresh install of this template, for example. Replaying it into a stock postgres:18 fails at that line and the tables are never created. Run the commands from a client that can reach both the bucket and the server — a workload inside the GVC, or your own machine with cpln port-forward RELEASE_NAME-pgvector 5432:5432 --gvc GVC_NAME open and --host=127.0.0.1 in place of the internal hostname.

This procedure is derived from the backup image’s script and the dump format it produces; it has not been exercised against a live install of this template. Rehearse a backup and restore before relying on it.

AWS S3
GCS
MinIO

export PGPASSWORD="PASSWORD"

aws s3 cp "s3://BUCKET_NAME/PREFIX/postgres-TIMESTAMP.sql.gz" - \
  | gunzip \
  | psql \
      --host=RELEASE_NAME-pgvector.GVC_NAME.cpln.local \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD

export PGPASSWORD="PASSWORD"

gsutil cp "gs://BUCKET_NAME/PREFIX/postgres-TIMESTAMP.sql.gz" - \
  | gunzip \
  | psql \
      --host=RELEASE_NAME-pgvector.GVC_NAME.cpln.local \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD

export PGPASSWORD="PASSWORD"
export AWS_ACCESS_KEY_ID="MINIO_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="MINIO_SECRET_KEY"
aws configure set default.s3.addressing_style path

aws s3 cp "s3://BUCKET_NAME/PREFIX/postgres-TIMESTAMP.sql.gz" - --endpoint-url "http://MINIO_ENDPOINT:9000" \
  | gunzip \
  | psql \
      --host=RELEASE_NAME-pgvector.GVC_NAME.cpln.local \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

already exists errors for the role, the database and the vector extension that the server created at first boot are expected; the rest of the script loads normally. Restore into an empty database (a fresh install, or one whose tables you have dropped) to avoid duplicate-object errors on existing tables. Use a PostgreSQL 18 psql — an older client prints invalid command \unrestrict at the end of a PostgreSQL 18 dump.

Rotating the Password

The server reads the secret only when the volume is first initialized, so change the password inside PostgreSQL first, then update the secret to match:

ALTER ROLE USERNAME WITH PASSWORD 'NEW-STRONG-PASSWORD';

Workloads resolve the secret when a replica starts, so an updated secret is not picked up by a running replica. The backup job reads it fresh on its next scheduled run; if PgBouncer is enabled, force a redeployment so it reconnects with the new password:

cpln workload force-redeployment RELEASE_NAME-pgbouncer --gvc GVC_NAME

Scaling and Availability

The server is pinned to one replica. Do not raise it — a second stateful replica gets its own volume, which is a second empty database rather than a replica.
PgBouncer is stateless; pgbouncer.replicas scales it horizontally for high connection counts.
Every cpln helm upgrade restarts the server, including the first upgrade after an install even when nothing changed. Plan each one as a short write outage. Data on the volume survives, including built HNSW graphs, which are not rebuilt.
A node failure reschedules the server and reattaches the same volume. The exposure is minutes of downtime, not data loss.
For automatic failover use PostgreSQL Highly Available, whose image also carries pgvector — but not the same build. Both hnsw and ivfflat exist there, so the gap is fixes and refinements rather than a missing index type; verify against your own queries before treating the two as interchangeable.

	pgvector template	postgres-highly-available
PostgreSQL	18	17
pgvector	0.8.6	0.8.0

Troubleshooting

Workload never becomes ready and cpln logs returns nothing

Symptom: the install succeeds, the workload stays not ready indefinitely, and cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-pgvector"}' --limit 50 --since 10m returns zero lines.Cause: config.credentialsSecretName names a secret that does not exist, so the container is never started. The message is only visible in status.versions[].message:

cpln workload get-deployments RELEASE_NAME-pgvector --gvc GVC_NAME -o yaml

The secret SECRET_NAME no longer exists. Workload updates are paused until the
secret is added or the reference to the secret removed.

Fix: create the secret as in Prerequisites. The deployment recovers on its own within several minutes, or run cpln workload force-redeployment RELEASE_NAME-pgvector --gvc GVC_NAME.

Install refused with 'Invalid config.extraExtensions entry'

Symptom: cpln helm install or upgrade stops before touching any resource:

Invalid config.extraExtensions entry "pg-trgm": an extension name must match ^[a-z][a-z0-9_]*$
(e.g. pg_trgm, pgcrypto, btree_gin).

Cause: an entry in config.extraExtensions contains a hyphen, a capital letter or other punctuation. Entries are interpolated into SQL, so the chart only accepts bare lower-case identifiers.Fix: use the extension’s exact name as PostgreSQL knows it — pg_trgm, not pg-trgm.

Server is healthy but an extension from config.extraExtensions is missing

Symptom: vector exists but CREATE EXTENSION for one of your extra extensions never ran, and the first-boot log shows ERROR: extension "NAME" is not available followed by a restart.Cause: the name is valid but the image does not ship that extension. The first-boot script stopped at that line; the restart found an initialized data directory and skipped initialization, so the remaining statements never ran.Fix: create the extensions the image does carry by hand with CREATE EXTENSION IF NOT EXISTS NAME;, and remove the unavailable one from config.extraExtensions. To start over with a corrected list, uninstall (which deletes the volume set) and reinstall.

ERROR: unrecognized configuration parameter "hnsw.ef_search", or recall varies between identical queries through PgBouncer

Symptom: through RELEASE_NAME-pgbouncer a plain SET hnsw.ef_search = ... sometimes errors with unrecognized configuration parameter, or SHOW hnsw.ef_search returns a value you did not set. Direct connections to RELEASE_NAME-pgvector behave normally.Cause: pgbouncer.poolMode: transaction hands the same server connection to different clients, so a session-level SET is not bound to the client that issued it.Fix: scope the setting with SET LOCAL inside a transaction (see Using pgvector), or set pgbouncer.poolMode: session.

CREATE INDEX fails with 'column cannot have more than 2000 dimensions for hnsw index'

Symptom: creating an hnsw (or ivfflat) index on a vector(N) column with N above 2,000 fails with this error, although inserting the vectors worked.Cause: a vector column stores up to 16,000 dimensions but pgvector indexes it only up to 2,000.Fix: store the embeddings as halfvec(N), which indexes up to 4,000 dimensions, or reduce the embedding dimensionality.

Client fails to connect to the public endpoint with sslmode=require

Symptom: a connection string carrying sslmode=require (or verify-ca / verify-full) cannot connect to the canonical endpoint, while the same credentials work without it.Cause: the image ships no TLS certificate, so the server does not offer SSL.Fix: use the libpq default sslmode=prefer, or sslmode=disable, and prefer the internal address RELEASE_NAME-pgvector.GVC_NAME.cpln.local over the public endpoint wherever possible.

Apply rejected with 'The ratio between cpu and minCpu must be less than 4:1'

Symptom: an install or upgrade fails and the server workload is not created or updated.Cause: resources.maxCpu is more than four times resources.minCpu, which the platform rejects on a stateful workload.Fix: raise resources.minCpu or lower resources.maxCpu so the ratio is at most 4:1.

Important Notes

Create the credentials secret before installing. A reference to a secret that does not exist wedges the workload with no log output; see Prerequisites for the one command that shows the reason.
The vector extension is created by this template, not by the image, in the database named in your credentials secret, on first boot only.
Credentials and config.extraExtensions are read only when the volume is first initialized. Add an extension later with CREATE EXTENSION IF NOT EXISTS ...; rotate a password with ALTER ROLE, then update the secret — see Rotating the Password.
PgBouncer in transaction mode leaks session settings between clients, including hnsw.ef_search. Use SET LOCAL inside a transaction, or poolMode: session.
publicAccess is unencrypted — the image ships no TLS certificate, so sslmode=require fails. Prefer internal access.
Do not scale the server past one replica. It is a single instance on a single volume, not a replicated cluster.
Every cpln helm upgrade restarts the server. Treat each one as a short planned write outage.
Restore with a PostgreSQL 18 psql, into a server that carries pgvector. A stock postgres:18 fails on the dump’s CREATE EXTENSION line.
cpln helm uninstall deletes the volume set and the database with it. Your credentials secret is yours and is left alone.

External References

pgvector Documentation

Upstream reference for vector types, operators, and index tuning

pgvector Image

The image this template deploys, and its available tags

PostgreSQL 18 Documentation

Official documentation for the server version shipped here

PgBouncer Documentation

PgBouncer configuration reference

pgvector Template

Source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Server and Resources

Credentials and Extensions

Storage

Internal Access

Public Access

PgBouncer

Backup

Connecting

Using pgvector

Operations

Backing Up

Backup Prerequisites

AWS S3

GCS

MinIO

Restoring a Backup

Rotating the Password

Scaling and Availability

Troubleshooting

Important Notes

External References

pgvector Documentation

pgvector Image

PostgreSQL 18 Documentation

PgBouncer Documentation

pgvector Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Server and Resources

​Credentials and Extensions

​Storage

​Internal Access

​Public Access

​PgBouncer

​Backup

​Connecting

​Using pgvector

​Operations

​Backing Up

​Backup Prerequisites

​AWS S3

​GCS

​MinIO

​Restoring a Backup

​Rotating the Password

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

pgvector Documentation

pgvector Image

PostgreSQL 18 Documentation

PgBouncer Documentation

pgvector Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Server and Resources

Credentials and Extensions

Storage

Internal Access

Public Access

PgBouncer

Backup

Connecting

Using pgvector

Operations

Backing Up

Backup Prerequisites

AWS S3

GCS

MinIO

Restoring a Backup

Rotating the Password

Scaling and Availability

Troubleshooting

Important Notes

External References