poimen-memory/K8S-DEPLOYMENT.md

Poimen Memory — K8s Deployment

Status

✅ CNPG Postgres cluster manifest created
✅ Added to homelab kustomization (single source of truth)
✅ Wave 2 — runs after ArgoCD bootstrap, before Poimen application

---

Architecture

Homelab ArgoCD
    ↓ (wave 2)
k8s/infra/databases/
    ├── namespaces.yaml (defines: iam, temporal)
    ├── authentik-db.yaml
    ├── temporal-db.yaml
    └── memory-db.yaml (NEW)
         ├── Cluster: memory-db (3 instances)
         ├── Extension: pgvector (768-dim embeddings)
         ├── Secret: memory-db-app (auto-generated)
         └── Service: memory-db-rw (auto-generated)
            ↓
Poimen Memory
    ├── PgRepo (reads memory-db-app secret)
    ├── Embeddings (cached in pgvector)
    └── Vault (projected from log)

---

Deployment

1. Homelab Sync (GitOps)

# Homelab repo already updated:
# - k8s/infra/databases/namespaces.yaml (added memory ns)
# - k8s/infra/databases/kustomization.yaml (added memory-db.yaml)
# - k8s/infra/databases/memory-db.yaml (NEW)

# No manual action needed — ArgoCD detects and deploys automatically

2. Verify Cluster Health

# After wave 2 syncs (check ArgoCD UI):
kubectl get clusters -n poimen
# NAME        PHASE       INSTANCES   READY
# memory-db   Healthy     3/3         3/3

# Check secret generated by CNPG:
kubectl get secret -n poimen | grep memory-db
# memory-db-app          kubernetes.io/basic-auth   2      5m

# Check service:
kubectl get svc -n poimen | grep memory-db
# memory-db-rw           ClusterIP   10.x.x.x   5432/TCP   5m

3. Verify pgvector Extension

# Port-forward to test:
kubectl port-forward -n poimen svc/memory-db-rw 5432:5432 &

# Test connection with generated credentials:
SECRET=$(kubectl get secret -n poimen memory-db-app -o jsonpath='{.data.password}' | base64 -d)
psql -h localhost -U app -d memory -c "CREATE EXTENSION IF NOT EXISTS vector; SELECT * FROM pg_extension WHERE extname='vector';"

---

Configuration

CNPG Cluster Spec

Setting	Value	Rationale
Instances	3	HA across nodes, tolerate 1 failure
Storage	10Gi	768-dim vectors @ 3KB each → millions fits
Image	PostgreSQL 16.2	Latest stable, pgvector 0.7.0 included
Class	longhorn-cnpg	Same as authentik/temporal (persistent)
CPU/Memory	250m/512Mi req, 1/2Gi limit	Same as other infra DBs
Extension	pgvector	Semantic search for embeddings
Affinity	Preferred spread + control-plane toleration	HA without deadlock

Connection

Poimen reads credentials from Kubernetes secret:

# Secret name: memory-db-app (auto-generated by CNPG)
# Keys: username, password
# Service: memory-db-rw (read-write endpoint)
# Host: memory-db-rw.poimen.svc.cluster.local
# Port: 5432
# Database: memory

Environment Variable

Poimen application deployment should set:

env:
  - name: DATABASE_URL
    valueFrom:
      secretKeyRef:
        name: memory-db-app
        key: username  # Will be "app"
  - name: DATABASE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: memory-db-app
        key: password

Example connection string:

postgresql://app:<password>@memory-db-rw.poimen.svc.cluster.local:5432/memory?sslmode=disable

---

Monitoring

CNPG generates Prometheus metrics on port 9187. Scrape config already in homelab if monitoring is enabled:

kubectl port-forward -n poimen svc/memory-db-metrics 9187:9187 &
curl localhost:9187/metrics | grep pgbouncer_pools

---

Rollback

If needed, delete the cluster:

kubectl delete cluster memory-db -n poimen
# CNPG will keep the PVC for 30 days (recovery window)
kubectl delete pvc -n poimen

---

Next: Poimen Application Deployment (Not Started)

Wave 3 will add Poimen application to ArgoCD that:

1. Reads memory-db-app secret for DB credentials
2. Runs PgRepo against memory-db-rw.poimen.svc.cluster.local
3. Caches embeddings in pgvector
4. Projects vault to Obsidian

---

Files

Homelab repo:

• k8s/infra/databases/memory-db.yaml — CNPG cluster manifest
• k8s/infra/databases/kustomization.yaml — Updated resources list
• k8s/infra/databases/namespaces.yaml — Updated with memory namespace

Poimen repo (reference only):

• k8s/infra/databases/memory-db.yaml — Same as homelab (mirror for reference)
• k8s/infra/databases/kustomization.yaml — Local kustomization for tests

---

Status

✅ M2.2 CNPG Postgres — Complete
⏳ M3 Application deployment — Waiting for Poimen Helm chart