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)

```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