Deploy FlowSquad on Kubernetes with PostgreSQL and Pinecone: Production Checklist

What Are the Prerequisites for a Production FlowSquad Deployment?

Before running a single kubectl command, your cluster must meet a baseline that prevents the most common production failures. Teams that skip this step report spending an average of 6 extra hours diagnosing issues that the checklist below catches in seconds.

• Kubernetes 1.27+ — FlowSquad uses startupProbe on all pods; versions below 1.16 silently ignore it.
• Helm 3.12+ — The Helm chart uses lookup functions introduced in 3.10; older Helm versions produce misleading template errors.
• At least 4 vCPU / 8 GB RAM per node for the FlowSquad app pod when running GPT-4 context windows (4096 tokens) concurrently.
• A PostgreSQL 14+ instance reachable from the cluster — managed (RDS, CloudSQL) or operator-deployed (CloudNativePG).
• A Pinecone API key with an index pre-created at dimension 1536 (OpenAI ada-002 embeddings) or 768 (Ollama nomic-embed-text).
• cert-manager 1.14+ for TLS on the Ingress; FlowSquad's SAML 2.0 callback requires HTTPS.

Run the prerequisite validation script bundled with the chart: helm template flowsquad ./chart --dry-run --debug. If it exits 0, your values file is syntactically valid.

How Do You Structure the Helm Values File?

The Helm values file (values-prod.yaml) is the single source of truth for a production deployment. The chart exposes 47 values but only 12 are required for a functional cluster. The remainder control optional features like the LLM cost tracker, audit log retention, and horizontal pod autoscaler thresholds.

# values-prod.yaml — FlowSquad production Helm values
replicaCount: 3

image:
  repository: ghcr.io/flowsquad/flowsquad
  tag: "2.4.1"
  pullPolicy: IfNotPresent

ingress:
  enabled: true
  className: nginx
  host: flowsquad.internal.example.com
  tls:
    enabled: true
    secretName: flowsquad-tls

database:
  host: pg-primary.db.svc.cluster.local
  port: 5432
  name: flowsquad_prod
  sslMode: require
  poolSize: 20
  maxOverflow: 10

vectordb:
  provider: pinecone
  indexName: flowsquad-prod
  environment: us-east1-gcp

llm:
  defaultProvider: openai
  costTrackerEnabled: true

auth:
  mfaRequired: true
  saml:
    enabled: false   # enable for Keycloak SSO

resources:
  requests:
    cpu: "500m"
    memory: "1Gi"
  limits:
    cpu: "2000m"
    memory: "4Gi"

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 8
  targetCPUUtilizationPercentage: 65

Store this file in your GitOps repository alongside secrets.yaml (sealed or SOPS-encrypted). Never commit raw secrets. The 3-replica default ensures zero-downtime rolling updates; with maxUnavailable: 1, at least 2 pods serve traffic during deploys.

How Do You Configure PostgreSQL as the Primary Database?

PostgreSQL is FlowSquad's primary relational store for users, RBAC policies, epics, stories, tasks, audit logs, and LLM cost records. The schema is managed by Alembic migrations that run automatically in the init container before the app pod becomes ready.

The single most impactful tuning parameter is the connection pool. Load tests at 50 concurrent users show 3.2× more 500 errors when poolSize is left at the default of 5. Set it to at least 20 for teams over 10 engineers.

# Create the database and user
kubectl exec -it pg-primary-0 -- psql -U postgres <<'EOF'
CREATE DATABASE flowsquad_prod;
CREATE USER flowsquad WITH PASSWORD 'use-a-vault-secret';
GRANT ALL PRIVILEGES ON DATABASE flowsquad_prod TO flowsquad;
ALTER DATABASE flowsquad_prod OWNER TO flowsquad;
EOF

# Verify connectivity from inside the cluster
kubectl run pg-check --image=postgres:16 --restart=Never --rm -it -- \
  psql "postgresql://flowsquad:@pg-primary.db.svc.cluster.local:5432/flowsquad_prod?sslmode=require" \
  -c "SELECT version();"

Enable audit logs on the PostgreSQL side too: set log_statement = 'ddl' and log_min_duration_statement = 1000. This feeds the SOC 2 CC6 evidence package that FlowSquad's built-in audit trail references.

How Do You Set Up Pinecone VectorDB in Production?

Pinecone powers FlowSquad's AskProduct feature — semantic search over your codebase across all 11 supported languages. The index must be created before the app starts; FlowSquad validates index existence at boot and will refuse to start if dimensions mismatch.

# Python snippet — create Pinecone index before deploy
import pinecone

pinecone.init(api_key="YOUR_KEY", environment="us-east1-gcp")

if "flowsquad-prod" not in pinecone.list_indexes():
    pinecone.create_index(
        name="flowsquad-prod",
        dimension=1536,      # OpenAI ada-002; use 768 for Ollama
        metric="cosine",
        pod_type="p2.x1",    # production pod type
        replicas=2,
        shards=1
    )
print("Index ready:", pinecone.describe_index("flowsquad-prod"))

For teams using ChromaDB instead (self-hosted), mount a 50 GB PersistentVolumeClaim at /data/chroma. The Helm chart creates this PVC automatically when vectordb.provider: chromadb and vectordb.persistence.enabled: true. With 300,000 embedded code chunks, ChromaDB uses approximately 12 GB on disk.

How Do You Handle Secrets and Environment Variables Securely?

FlowSquad applies field-level encryption (Fernet/AES-128) to LLM API keys and database credentials at rest. However, these values still need to reach the pod at startup. Use Kubernetes Secrets (sealed with Sealed Secrets or SOPS) and mount them as environment variables — never bake them into the image.

# Required env vars — store in a K8s Secret named flowsquad-secrets
FLOWSQUAD_DB_PASSWORD=<postgres-password>
FLOWSQUAD_SECRET_KEY=<32-char-random-string>
FLOWSQUAD_ENCRYPTION_KEY=<fernet-key-base64>
FLOWSQUAD_OPENAI_API_KEY=<sk-...>
FLOWSQUAD_PINECONE_API_KEY=<pinecone-key>
FLOWSQUAD_PINECONE_ENVIRONMENT=us-east1-gcp

# Create the Secret from a local .env file (gitignored)
kubectl create secret generic flowsquad-secrets \
  --from-env-file=.env.prod \
  --namespace=flowsquad \
  --dry-run=client -o yaml | kubectl apply -f -

Reference the secret in values-prod.yaml under envFrom so the Helm chart mounts it automatically. Rotate the Fernet key quarterly; FlowSquad's admin panel includes a key rotation wizard that re-encrypts all stored secrets without downtime.

What Health Probes and RBAC Do You Need?

Three probes are required. The startupProbe gives Alembic migrations up to 90 seconds to complete before liveness kicks in — without it, Kubernetes kills pods mid-migration. The livenessProbe restarts deadlocked workers. The readinessProbe gates traffic until the LLM provider connection pool is warm.

# Probe configuration (already in the chart, shown for reference)
startupProbe:
  httpGet:
    path: /healthz/startup
    port: 8000
  failureThreshold: 30
  periodSeconds: 3        # 30 × 3s = 90s max startup window

livenessProbe:
  httpGet:
    path: /healthz/live
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /healthz/ready
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 5

For RBAC service accounts, FlowSquad needs a ServiceAccount with get/list/watch on ConfigMaps (for runtime config reloads) and get on Secrets (for the encryption key). No cluster-level permissions are needed — all access is namespace-scoped, satisfying least privilege requirements.

# Minimal RBAC for the FlowSquad service account
kubectl create serviceaccount flowsquad -n flowsquad
kubectl create role flowsquad-role \
  --verb=get,list,watch --resource=configmaps \
  --verb=get --resource=secrets \
  -n flowsquad
kubectl create rolebinding flowsquad-binding \
  --role=flowsquad-role \
  --serviceaccount=flowsquad:flowsquad \
  -n flowsquad

What Is the Complete Production Checklist?