Rework bundled postgres helm and templates

DEVELOPMENT.md

@@ -126,7 +126,9 @@ This installs the following components into your cluster:
 | Prometheus     | Metrics collection                   | `kagent`       |
 | Metrics Server | Kubernetes resource metrics          | `kube-system`  |
 
-PostgreSQL (with pgvector) is deployed automatically as part of `make helm-install` via the bundled Helm chart. The optional addons above provide observability components.
+PostgreSQL is deployed automatically as part of `make helm-install` via the bundled Helm chart. The optional addons above provide observability components.
+
+> **pgvector:** The default bundled PostgreSQL image (`postgres:18`) does not include the pgvector extension. If you need vector features (e.g. long-term memory), either use an external PostgreSQL instance with pgvector installed, or override the bundled image to `pgvector/pgvector:pg18-trixie` and set `database.postgres.vectorEnabled=true`. The `make helm-install` target does this automatically for local development.
 
 Verify the database connection by checking the controller logs:
 

Makefile

@@ -375,6 +375,10 @@ helm-install-provider: helm-version check-api-key
 		--set kmcp.enabled=$(KMCP_ENABLED) \
 		--set kmcp.image.tag=$(KMCP_VERSION) \
 		--set querydoc.openai.apiKey=$(OPENAI_API_KEY) \
+		--set database.postgres.bundled.image.repository=pgvector \
+		--set database.postgres.bundled.image.name=pgvector \
+		--set database.postgres.bundled.image.tag=pg18-trixie \
+		--set database.postgres.vectorEnabled=true \
 		$(KAGENT_HELM_EXTRA_ARGS)
 
 .PHONY: helm-install

contrib/cncf/technical-review.md

@@ -3,9 +3,9 @@
 _This document provides a General Technical Review of the kagent project. This is a living document that demonstrates to the Technical Advisory Group (TAG) that the project satisfies the Engineering Principle requirements for moving levels. This document follows the template outlined [in the TOC subproject review](https://github.com/cncf/toc/blob/main/toc_subprojects/project-reviews-subproject/general-technical-questions.md)_
 
 - **Project:** kagent
-- **Project Version:** v0.7.5
+- **Project Version:** v0.8.0
 - **Website:** [https://kagent.dev](https://kagent.dev)
-- **Date Updated:** 2025-12-01
+- **Date Updated:** 2026-03-19
 - **Template Version:** v1.0
 - **Description:** kagent is a Kubernetes native framework for building AI agents. Kubernetes is the most popular orchestration platform for running workloads, and **kagent** makes it easy to build, deploy and manage AI agents in Kubernetes. The **kagent** framework is designed to be easy to understand and use, and to provide a flexible and powerful way to build and manage AI agents.
 
@@ -326,7 +326,7 @@ Default values can be found in [helm/kagent/values.yaml](https://github.com/kage
 **Additional Configurations:**
 For production use, configure:
 
-- PostgreSQL database connection (`database.type=postgres`, `database.postgres.url`)
+- External PostgreSQL connection (set `database.postgres.bundled.enabled=false` and set either `database.postgres.url` or `database.postgres.urlFile`)
 - LLM API keys via Secrets (`providers.openAI.apiKeySecretRef`)
 - TLS for external LLM connections (`modelConfig.tls`)
 - Resource limits based on workload (`agents.*.resources`)

helm/kagent/templates/NOTES.txt

@@ -59,4 +59,27 @@ TROUBLESHOOTING:
 DOCUMENTATION:
   Visit https://kagent.dev for comprehensive documentation and examples.
 
+{{ if .Values.database.postgres.bundled.enabled -}}
+################################################################################
+{{- if and (eq .Values.database.postgres.url "") (eq .Values.database.postgres.urlFile "") }}
+# WARNING: BUNDLED DATABASE IN USE                                             #
+################################################################################
+  The bundled PostgreSQL instance is enabled. It is intended for development and
+  evaluation only — not suitable for production use. Data may be lost if the
+  pod is restarted or rescheduled.
+
+  To use an external database, set:
+    database.postgres.url=<your-connection-string> or database.postgres.urlFile=<path>
+{{- else }}
+# NOTE: BUNDLED DATABASE DEPLOYED BUT NOT IN USE BY CONTROLLER                 #
+################################################################################
+  The bundled PostgreSQL pod is running, but the controller is connected to an
+  external database (database.postgres.url or database.postgres.urlFile is set).
+
+  To connect the controller to the bundled instance instead, unset url/urlFile:
+    database.postgres.url=""
+  To stop deploying the bundled pod entirely, set:
+    database.postgres.bundled.enabled=false
+{{- end }}
+{{- end }}
 ################################################################################

helm/kagent/templates/_helpers.tpl

@@ -122,14 +122,18 @@ PostgreSQL service name for the bundled postgres instance
 {{- end -}}
 
 {{/*
-PostgreSQL URL - auto-computed from bundled config when url is empty, otherwise uses database.postgres.url
+Bundled PostgreSQL image - constructs the full image reference from registry/repository/name/tag
 */}}
-{{- define "kagent.postgresqlUrl" -}}
-{{- if not (eq .Values.database.postgres.url "") -}}
-{{- .Values.database.postgres.url -}}
-{{- else -}}
-{{- printf "postgres://%s:%s@%s.%s.svc.cluster.local:5432/%s" .Values.database.postgres.bundled.user .Values.database.postgres.bundled.password (include "kagent.postgresqlServiceName" .) (include "kagent.namespace" .) .Values.database.postgres.bundled.database -}}
+{{- define "kagent.postgresql.image" -}}
+{{- $pg := .Values.database.postgres.bundled -}}
+{{- printf "%s/%s/%s:%s" $pg.image.registry $pg.image.repository $pg.image.name $pg.image.tag -}}
 {{- end -}}
+
+{{/*
+Password secret name - returns the chart-managed Secret name for POSTGRES_PASSWORD.
+*/}}
+{{- define "kagent.passwordSecretName" -}}
+{{- printf "%s-postgresql" (include "kagent.fullname" .) -}}
 {{- end -}}
 
 {{/*

helm/kagent/templates/controller-configmap.yaml

@@ -51,11 +51,6 @@ data:
   {{- if .Values.proxy.url }}
   PROXY_URL: {{ .Values.proxy.url | quote }}
   {{- end }}
-  {{- if not (eq .Values.database.postgres.urlFile "") }}
-  POSTGRES_DATABASE_URL_FILE: {{ .Values.database.postgres.urlFile | quote }}
-  {{- else }}
-  POSTGRES_DATABASE_URL: {{ include "kagent.postgresqlUrl" . | quote }}
-  {{- end }}
   DATABASE_VECTOR_ENABLED: {{ .Values.database.postgres.vectorEnabled | quote }}
   STREAMING_INITIAL_BUF_SIZE: {{ .Values.controller.streaming.initialBufSize | quote }}
   STREAMING_MAX_BUF_SIZE: {{ .Values.controller.streaming.maxBufSize | quote }}

helm/kagent/templates/controller-deployment.yaml

@@ -14,6 +14,7 @@ spec:
     metadata:
       annotations:
         checksum/configmap: {{ include (print $.Template.BasePath "/controller-configmap.yaml") . | sha256sum }}
+        checksum/secret: {{ include (print $.Template.BasePath "/postgresql-secret.yaml") . | sha256sum }}
         {{- with .Values.controller.podAnnotations }}
           {{- toYaml . | nindent 8 }}
         {{- end }}
@@ -60,6 +61,23 @@ spec:
               valueFrom:
                 fieldRef:
                   fieldPath: spec.nodeName
+            {{- if .Values.database.postgres.urlFile }}
+            - name: POSTGRES_DATABASE_URL_FILE
+              value: {{ .Values.database.postgres.urlFile | quote }}
+            {{- else if .Values.database.postgres.url }}
+            - name: POSTGRES_DATABASE_URL
+              value: {{ .Values.database.postgres.url | quote }}
+            {{- else if .Values.database.postgres.bundled.enabled }}
+            - name: POSTGRES_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "kagent.passwordSecretName" . }}
+                  key: POSTGRES_PASSWORD
+            - name: POSTGRES_DATABASE_URL
+              value: {{ printf "postgres://kagent:$(POSTGRES_PASSWORD)@%s.%s.svc.cluster.local:5432/kagent?sslmode=disable" (include "kagent.postgresqlServiceName" .) (include "kagent.namespace" .) | quote }}
+            {{- else }}
+            {{ fail "No database connection configured. Set database.postgres.url, database.postgres.urlFile, or enable database.postgres.bundled." }}
+            {{- end }}
             {{- with .Values.controller.env }}
               {{- toYaml . | nindent 12 }}
             {{- end }}

helm/kagent/templates/postgresql-secret.yaml

@@ -0,0 +1,13 @@
+{{- if .Values.database.postgres.bundled.enabled }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "kagent.passwordSecretName" . }}
+  namespace: {{ include "kagent.namespace" . }}
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+    app.kubernetes.io/component: database
+type: Opaque
+data:
+  POSTGRES_PASSWORD: {{ "kagent" | b64enc | quote }}
+{{- end }}

helm/kagent/templates/postgresql.yaml

@@ -1,90 +1,125 @@
-{{- if and (eq .Values.database.postgres.url "") (eq .Values.database.postgres.urlFile "") }}
----
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: {{ include "kagent.fullname" . }}-postgresql
-  namespace: {{ include "kagent.namespace" . }}
-  labels:
-    {{- include "kagent.labels" . | nindent 4 }}
-    app.kubernetes.io/component: postgresql
-data:
-  POSTGRES_DB: {{ .Values.database.postgres.bundled.database | quote }}
-  POSTGRES_USER: {{ .Values.database.postgres.bundled.user | quote }}
-  POSTGRES_PASSWORD: {{ .Values.database.postgres.bundled.password | quote }}
+{{- if .Values.database.postgres.bundled.enabled }}
+{{- $pg := .Values.database.postgres.bundled }}
+{{- $fullname := include "kagent.postgresqlServiceName" . }}
 ---
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
-  name: {{ include "kagent.fullname" . }}-postgresql
+  name: {{ $fullname }}
   namespace: {{ include "kagent.namespace" . }}
   labels:
     {{- include "kagent.labels" . | nindent 4 }}
-    app.kubernetes.io/component: postgresql
+    app.kubernetes.io/component: database
 spec:
   accessModes:
     - ReadWriteOnce
   resources:
     requests:
-      storage: {{ .Values.database.postgres.bundled.storage | quote }}
+      storage: {{ $pg.storage | quote }}
 ---
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: {{ include "kagent.fullname" . }}-postgresql
+  name: {{ $fullname }}
   namespace: {{ include "kagent.namespace" . }}
   labels:
     {{- include "kagent.labels" . | nindent 4 }}
-    app.kubernetes.io/component: postgresql
+    app.kubernetes.io/component: database
 spec:
   replicas: 1
+  strategy:
+    type: Recreate
   selector:
     matchLabels:
       {{- include "kagent.selectorLabels" . | nindent 6 }}
-      app.kubernetes.io/component: postgresql
+      app.kubernetes.io/component: database
   template:
     metadata:
       labels:
         {{- include "kagent.selectorLabels" . | nindent 8 }}
-        app.kubernetes.io/component: postgresql
+        app.kubernetes.io/component: database
     spec:
+      securityContext:
+        fsGroup: 999
+        runAsUser: 999
+        runAsGroup: 999
+        runAsNonRoot: true
       containers:
         - name: postgresql
-          image: {{ .Values.database.postgres.bundled.image | quote }}
+          image: {{ include "kagent.postgresql.image" . }}
+          imagePullPolicy: {{ $pg.image.pullPolicy }}
+          securityContext:
+            allowPrivilegeEscalation: false
           ports:
-            - containerPort: 5432
-          envFrom:
-            - configMapRef:
-                name: {{ include "kagent.fullname" . }}-postgresql
-          volumeMounts:
-            - name: postgresql-storage
-              mountPath: /var/lib/postgresql
+            - name: postgresql
+              containerPort: 5432
+              protocol: TCP
+          env:
+            - name: POSTGRES_DB
+              value: "kagent"
+            - name: POSTGRES_USER
+              value: "kagent"
+            - name: POSTGRES_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "kagent.passwordSecretName" . }}
+                  key: POSTGRES_PASSWORD
+            - name: PGDATA
+              value: /var/lib/postgresql/data/pgdata
+          livenessProbe:
+            exec:
+              command:
+                - pg_isready
+                - -U
+                - kagent
+                - -d
+                - kagent
+            initialDelaySeconds: 20
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 6
+            successThreshold: 1
+          readinessProbe:
+            exec:
+              command:
+                - pg_isready
+                - -U
+                - kagent
+                - -d
+                - kagent
+            initialDelaySeconds: 5
+            periodSeconds: 5
+            timeoutSeconds: 3
+            failureThreshold: 3
+            successThreshold: 1
+          {{- if $pg.resources }}
           resources:
-            requests:
-              memory: "256Mi"
-              cpu: "250m"
-            limits:
-              memory: "512Mi"
-              cpu: "500m"
+            {{- toYaml $pg.resources | nindent 12 }}
+          {{- end }}
+          volumeMounts:
+            - name: data
+              mountPath: /var/lib/postgresql/data
       volumes:
-        - name: postgresql-storage
+        - name: data
           persistentVolumeClaim:
-            claimName: {{ include "kagent.fullname" . }}-postgresql
+            claimName: {{ $fullname }}
 ---
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ include "kagent.postgresqlServiceName" . }}
+  name: {{ $fullname }}
   namespace: {{ include "kagent.namespace" . }}
   labels:
     {{- include "kagent.labels" . | nindent 4 }}
-    app.kubernetes.io/component: postgresql
+    app.kubernetes.io/component: database
 spec:
+  type: ClusterIP
+  ports:
+    - name: postgresql
+      port: 5432
+      targetPort: postgresql
+      protocol: TCP
   selector:
     {{- include "kagent.selectorLabels" . | nindent 4 }}
-    app.kubernetes.io/component: postgresql
-  ports:
-    - port: 5432
-      targetPort: 5432
-  type: ClusterIP
+    app.kubernetes.io/component: database
 {{- end }}