Kubernetes

Deploy Stategraph on Kubernetes using the official Helm chart.

Prerequisites

• Kubernetes 1.19+
• Helm 3.0+
• kubectl configured for your cluster
• Ingress controller (optional, for external access)
• Access to the Stategraph Helm chart and server image — they're distributed privately so we can make sure your team has the support it needs; reach out and we'll get you set up

Quick Start

1. Add the Helm repository:

helm repo add stategraph <stategraph-helm-repo>  # repo URL provided when you get access: https://stategraph.com/contact
helm repo update

2. Install Stategraph:

helm install stategraph stategraph/stategraph \
  --namespace stategraph \
  --create-namespace

3. Access Stategraph:

For local testing:

kubectl port-forward -n stategraph svc/stategraph 8080:80

Then access at http://localhost:8080

Cookie Security

Stategraph derives cookie security from STATEGRAPH_UI_BASE:

• https:// URLs → cookies are set with the Secure flag (recommended for production)
• http:// URLs → cookies are set without the Secure flag (suitable for development or internal networks)

For example, setting stategraph.ui.base=http://myserver:8080 allows authentication over plain HTTP.

Production Installation

For production with HTTPS and ingress:

helm install stategraph stategraph/stategraph \
  --namespace stategraph \
  --create-namespace \
  --set stategraph.ui.base="https://stategraph.example.com" \
  --set stategraph.ui.oauthRedirectBase="https://stategraph.example.com" \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host="stategraph.example.com" \
  --set ingress.hosts[0].paths[0].path="/" \
  --set ingress.hosts[0].paths[0].pathType="Prefix" \
  --set ingress.tls[0].secretName="stategraph-tls" \
  --set ingress.tls[0].hosts[0]="stategraph.example.com" \
  --set ingress.annotations."cert-manager\.io/cluster-issuer"="letsencrypt-prod"

Configuration Options

View all available configuration options:

helm show values stategraph/stategraph

Common configurations:

For all available options, see the chart documentation included with your private chart access, or reach out and we'll walk you through it.

Health Checks

Stategraph provides two health check endpoints for Kubernetes probes:

The Helm chart configures these probes automatically. If you need to customize them:

# values.yaml
livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 10

During startup, database migrations run before the backend starts. The liveness probe passes immediately (nginx is up), while the readiness probe will fail until migrations complete and the backend is ready.

For more details, see the Health Checks reference.

Upgrading

helm repo update
helm upgrade stategraph stategraph/stategraph -n stategraph

Uninstalling

helm uninstall stategraph -n stategraph
kubectl delete namespace stategraph

Using External PostgreSQL

To use an existing PostgreSQL database instead of the bundled one:

helm install stategraph stategraph/stategraph \
  --namespace stategraph \
  --create-namespace \
  --set postgresql.enabled=false \
  --set postgresql.host="your-postgres-host.example.com" \
  --set postgresql.port=5432 \
  --set postgresql.auth.username="stategraph" \
  --set postgresql.auth.existingSecret="external-db-secret"

Create the secret with your database password:

kubectl create secret generic external-db-secret \
  --from-literal=db-password='your-password' \
  -n stategraph

Authentication

To enable OAuth authentication, configure the OAuth settings during installation:

helm install stategraph stategraph/stategraph \
  --namespace stategraph \
  --create-namespace \
  --set stategraph.oauth.enabled=true \
  --set stategraph.oauth.type="google" \
  --set stategraph.oauth.clientId="your-client-id" \
  --set stategraph.oauth.clientSecret="your-client-secret"

See the Authentication guide for detailed OAuth setup instructions.

Enable cost estimation

Cost analysis is off by default. The pricing service ships inside the server image; turn it on by
setting STATEGRAPH_COST_ENABLED=true on the stategraph container. Set it as part of the
Deployment so every new or rescheduled pod comes up with cost on. The bundled pricing service runs
in the same container, so STATEGRAPH_PRICING_SERVICE_URL already defaults to http://localhost:8090
— set it only to point at an external pricing service.

Add it to the container's env (values shape may differ by chart version — run
helm show values stategraph/stategraph to confirm where extra environment variables go):

# values.yaml
env:
  - name: STATEGRAPH_COST_ENABLED
    value: "true"

Then roll out the change:

helm upgrade stategraph stategraph/stategraph -n stategraph -f values.yaml

On first boot the pricing service loads the price book into the cloud_pricing database in the
background, so the server and UI stay available immediately. Make sure cloud_pricing has durable
storage (a volume or managed PostgreSQL). See Cost Setup for verification,
refresh cadence, and air-gapped installs.

Troubleshooting

# Check pod status
kubectl get pods -n stategraph

# View logs
kubectl logs -n stategraph -l app.kubernetes.io/name=stategraph

# Check events
kubectl get events -n stategraph --sort-by='.lastTimestamp'

Next Steps

• Set up Velocity — parallel plan and apply for Terraform
• Enable cost estimation — surface cost in your terraform plan output
• Set up OAuth authentication