Deploy Poimen Memory K8s cluster with ArgoCD tracking (M2.2, M3.5-M3.7)

2026-08-22 23:13:42 -07:00
parent af9c5ba01b
commit 695e115212
67 changed files with 8438 additions and 24 deletions
@@ -0,0 +1,179 @@
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```yaml
+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:
+
+```bash
+kubectl port-forward -n poimen svc/memory-db-metrics 9187:9187 &
+curl localhost:9187/metrics | grep pgbouncer_pools
+```
+
+---
+
+## Rollback
+
+If needed, delete the cluster:
+
+```bash
+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
+