poimen-workflows/k8s/temporal/README.md

Temporal Server Deployment for Poimen Agent

Phase 1.1: Temporal Infrastructure

This directory contains Kubernetes manifests for deploying Temporal Server with all required backends.

Components

1. PostgreSQL StatefulSet (01-postgres-statefulset.yaml)

   • Persistent storage for event log
   • Two databases: temporal (events) + temporal_visibility
   • PVC: 10Gi
   • Health checks: liveness + readiness
   • Port: 5432

2. Elasticsearch StatefulSet (02-elasticsearch-statefulset.yaml)

   • Search engine for workflow visibility
   • Single-node cluster
   • PVC: 20Gi
   • Port: 9200 (HTTP), 9300 (transport)
   • Health checks: HTTP GET /_cluster/health

3. Temporal Server StatefulSet (03-temporal-server-statefulset.yaml)

   • Main Temporal server instance
   • Image: temporalio/auto-setup:1.20.0
   • Services:
     • Frontend: 7233 (gRPC)
     • Matching: 7235 (internal)
     • History: 7234 (internal)
     • Worker: 7239 (internal)
   • Headless service for StatefulSet communication
   • ClusterIP service for worker connections

4. Temporal UI Deployment (04-temporal-ui-deployment.yaml)

   • Web UI for workflow visualization
   • Image: temporalio/ui:2.10.0
   • Connects to: temporal-frontend:7233
   • Port: 3000 (internal), 3000 (external LoadBalancer)

Deployment

# Deploy all Temporal components
kubectl apply -k k8s/temporal/

# Wait for StatefulSets to be ready
kubectl wait --for=condition=ready pod -l app=temporal-server -n temporal --timeout=300s

# Verify deployment
kubectl get all -n temporal

# Port forward to Temporal UI
kubectl port-forward -n temporal svc/temporal-ui-external 3000:3000
# Access at http://localhost:3000

Persistence

• PostgreSQL: 10Gi PVC for event log + visibility
• Elasticsearch: 20Gi PVC for search index
• Both use dynamic provisioning (PersistentVolumeClaim)

Security Considerations

1. PostgreSQL password in Secret: temporal-postgres-secret

   • Default: "temporal-password-changeme"
   • Must be changed for production

2. Elasticsearch security disabled (xpack.security.enabled: false)

   • Must be enabled for production

3. Services use ClusterIP (internal only)

   • Temporal UI exposed via LoadBalancer for demo
   • Should use Ingress for production

Health Checks

• PostgreSQL: pg_isready liveness + readiness
• Elasticsearch: HTTP GET to /_cluster/health
• Temporal Server: TCP socket probe to port 7233
• Temporal UI: HTTP GET to / (port 8080)

Monitoring

Temporal Server exports Prometheus metrics on port 9090:

kubectl port-forward -n temporal svc/temporal-server 9090:9090
# Metrics available at http://localhost:9090/metrics

Troubleshooting

# Check Temporal Server logs
kubectl logs -n temporal -f statefulset/temporal-server

# Check PostgreSQL logs
kubectl logs -n temporal -f statefulset/temporal-postgres

# Check Elasticsearch logs
kubectl logs -n temporal -f statefulset/temporal-elasticsearch

# Check Temporal UI logs
kubectl logs -n temporal -f deployment/temporal-ui

# Debug connectivity
kubectl run -it --rm debug --image=alpine --restart=Never -n temporal -- sh
# Inside pod:
# apk add postgresql-client
# psql -h temporal-postgres -U postgres -d temporal
# apk add curl
# curl http://temporal-elasticsearch:9200/_cluster/health

Next Phase (1.2)

After Temporal deployment is verified:

1. Add Temporal Rust SDK to project
2. Create worker registration
3. Setup task queue polling

---

Status: Phase 1.1 Implementation ✅ Created: 2025-01-30 Effort: 150 LOC (manifests)