Skip to content

Rework bundled postgres helm and templates#1527

Open
iplay88keys wants to merge 8 commits intomainfrom
iplay88keys/bundled-postgres-helm-changes
Open

Rework bundled postgres helm and templates#1527
iplay88keys wants to merge 8 commits intomainfrom
iplay88keys/bundled-postgres-helm-changes

Conversation

@iplay88keys
Copy link
Contributor

@iplay88keys iplay88keys commented Mar 19, 2026

Description

Follow-up to: #1503

Warning

If you are using a vector enabled DB for your external database, set database.postgres.vectorEnabled to true as the default value has changed to false in order to use the official Postgres image instead of the pgvector image for the bundled database.

If you were using the bundled PostgreSQL and want to keep the data, read the mitigation section below. A direct upgrade will initialize a fresh database.

This PR reworks how kagent's bundled PostgreSQL is configured and deployed. The main goals are:

  • Security: credentials are now stored in a Kubernetes Secret instead of a ConfigMap
  • Reliability: the bundled pod now has liveness/readiness probes, a Recreate strategy, non-root security context, and a correctly configured PGDATA path that survives restarts
  • Flexibility: bundled.enabled and url/urlFile are now independent — you can keep the bundled pod running while pointing the controller at an external database, which makes migration easier
  • Clarity: the bundled instance is more explicitly scoped to dev/eval use; the image is switched to standard postgres:18 in the helm chart and the toggle is an explicit flag rather than an implicit side effect of leaving url empty. The local make target deploys pgvector:pg18-trixie for developing against a vector enabled database.

Note that this is a breaking change from the bundled Postgres added earlier this week.

What changed in the helm chart for the bundled image:

Before After
Image pgvector/pgvector:pg18-trixie docker.io/library/postgres:18
Username postgres kagent (hardcoded)
Database postgres kagent (hardcoded)
Mount path /var/lib/postgresql /var/lib/postgresql/data
PGDATA /var/lib/postgresql/data (default) /var/lib/postgresql/data/pgdata (explicit)
Password storage ConfigMap (plaintext) Secret (base64)
Toggle implicit (empty url/urlFile) database.postgres.bundled.enabled (default: true)

Restarts and helm upgrades preserve data in the bundled Postgres instance correctly once on the new chart.

Mitigation

The bundled PostgreSQL is intended for local development. If you don't need to keep existing data, just upgrade — the new chart initializes a fresh database at a different path on the existing PVC and will not touch the old data directory.

If you want to keep existing local data, you'll need to back up first and restore after upgrading.

Backup (run before upgrading):

kubectl exec -n kagent deployment/kagent-postgresql -- \
  pg_dump -U postgres postgres > kagent-backup.sql

Restore (run after upgrading):
Note The helm chart by default uses the Postgres image without vector support whereas the helm install make target overwrites the image to use the pgvector image.

Restoring when overwriting the bundled image to use the pgvector image:

PGPOD=$(kubectl get pod -n kagent -l app.kubernetes.io/component=database -o name | head -1)
kubectl exec -i -n kagent $PGPOD -- psql -U kagent -d kagent < kagent-backup.sql

Database configuration reference

bundled.enabled and url/urlFile are independent controls:

  • database.postgres.bundled.enabled controls whether the bundled PostgreSQL pod and its PVC are deployed. It has no effect on which database the controller connects to.
  • database.postgres.url / database.postgres.urlFile control what the controller connects to. When either is set, the controller uses it. When both are empty, the controller connects to the bundled instance.

This means you can have the bundled pod running while the controller points at an external database — useful for migrating data from the bundled Postgres to an external Postgres.

Connection precedence (controller only): urlFile > url > bundled connection string.

Scenario bundled.enabled url / urlFile Bundled pod deployed? Controller connects to
Default (dev/eval) true unset yes bundled
External DB, no bundled pod false set no external
External DB, bundled pod kept running true set yes external
Bundled disabled, no external set false unset no nothing (misconfigured)

urlFile is recommended when your connection string contains credentials — it keeps secrets out of Helm values and the Kubernetes Deployment spec:

database:
  postgres:
    urlFile: /var/secrets/db-url   # path inside the controller container

Mount the secret yourself via controller.volumes / controller.volumeMounts:

controller:
  volumes:
    - name: db-secret
      secret:
        secretName: my-postgres-url-secret
  volumeMounts:
    - name: db-secret
      mountPath: /var/secrets
      readOnly: true

url is suitable when credentials are already managed externally (e.g. injected by a secrets manager at deploy time):

database:
  postgres:
    url: "postgres://user:pass@db.example.com:5432/kagent?sslmode=require"

bundled deploys a single-replica PostgreSQL pod with a PersistentVolumeClaim. Not suitable for production — no replication, no backups, data is lost if the PVC is deleted:

database:
  postgres:
    bundled:
      enabled: true          # default
      storage: 500Mi
      image:
        registry: docker.io
        repository: library
        name: postgres
        tag: "18"

Signed-off-by: Jeremy Alvis <jeremy.alvis@solo.io>
Signed-off-by: Jeremy Alvis <jeremy.alvis@solo.io>
Signed-off-by: Jeremy Alvis <jeremy.alvis@solo.io>
Signed-off-by: Jeremy Alvis <jeremy.alvis@solo.io>
Signed-off-by: Jeremy Alvis <jeremy.alvis@solo.io>
@iplay88keys iplay88keys marked this pull request as ready for review March 19, 2026 19:49
@iplay88keys iplay88keys requested a review from EItanya as a code owner March 19, 2026 19:49
Copilot AI review requested due to automatic review settings March 19, 2026 19:49
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR reworks how kagent's bundled PostgreSQL is configured and deployed, following up on PR #1503. The main improvements include moving credentials from ConfigMap to Kubernetes Secrets, adding health probes and proper security context, making the bundled and external database configuration independent, and switching the default bundled image from pgvector to the standard PostgreSQL image for dev/eval use.

Changes:

  • Moved PostgreSQL password storage from ConfigMap (plaintext) to Secret (base64-encoded)
  • Added liveness/readiness probes to the bundled PostgreSQL Deployment using pg_isready
  • Implemented non-root security context with UID 999 and fixed PGDATA path to survive restarts
  • Made bundled database deployment independent from external database configuration
  • Changed default bundled image to docker.io/library/postgres:18 (without pgvector)
  • Updated Makefile to use pgvector image for local development
  • Added comprehensive Helm unit tests for PostgreSQL configuration

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
helm/kagent/values.yaml Restructured bundled postgres config with explicit enabled flag and image subfields
helm/kagent/templates/postgresql.yaml Complete rewrite with PVC, Deployment, and Service; moved to Secret-based password
helm/kagent/templates/postgresql-secret.yaml New file creating Kubernetes Secret for password
helm/kagent/templates/controller-deployment.yaml Updated to reference password Secret and properly handle database URL configuration
helm/kagent/templates/controller-configmap.yaml Removed database URL configuration (moved to Deployment env)
helm/kagent/templates/_helpers.tpl Added helpers for image building, secret naming, and connection string
helm/kagent/tests/postgresql_test.yaml New comprehensive test suite for bundled PostgreSQL configuration
Makefile Added pgvector image overrides for local development
DEVELOPMENT.md Updated documentation to clarify pgvector availability

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Signed-off-by: Jeremy Alvis <jeremy.alvis@solo.io>
…nd url/urlfile work

Signed-off-by: Jeremy Alvis <jeremy.alvis@solo.io>
@iplay88keys iplay88keys marked this pull request as draft March 19, 2026 20:25
Signed-off-by: Jeremy Alvis <jeremy.alvis@solo.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants