Deploy with Helm

The Helm chart in infra/helm/caracal renders production-shaped Kubernetes resources for API, STS, Gateway, Audit, Coordinator, and optional Control.

Rendered Resources

Resource	Purpose
Deployment	API, Audit, Coordinator, and Control when enabled.
StatefulSet	STS and Gateway when replay persistence is enabled.
Job	Pre-install/pre-upgrade Postgres migrations.
Service	ClusterIP service per enabled component.
Ingress	Optional external API and Gateway endpoints.
NetworkPolicy	Default-deny with explicit internal, storage, DNS, OTLP, HTTPS, and custom egress controls.
PDB/HPA	Availability and scaling controls per service.
ServiceMonitor/PrometheusRule	Metrics scraping and built-in alert recipes.

Profile Selection

The chart ships three overlays on top of values.yaml. Pick one explicitly — values.production.yaml is the canonical enterprise install path:

Overlay	`global.mode`	Posture	Use for
`values.production.yaml`	`stable`	Fail-closed; replicas, PDBs, anti-affinity baked in	Production (canonical)
`values.rc.yaml`	`rc`	Same fail-closed trust boundary; release-candidate build may be functionally unstable	Staging / pre-release validation
`values.dev.yaml`	`dev`	Relaxed, single-host conveniences	Local evaluation only

Always pass the chosen overlay with --values; never install on bare values.yaml.

Minimal Install Shape

helm upgrade --install caracal infra/helm/caracal \
  --namespace caracal \
  --create-namespace \
  --values infra/helm/caracal/values.production.yaml

Before installing, provide the runtime Secret named by secrets.runtimeSecretName or set secrets.create=true with plaintext values only for a controlled evaluation environment.

For a managed-cloud install with the runtime Secret provisioned by the External Secrets Operator, a production overlay, and cert-manager TLS ingress, follow Deploy on Managed Kubernetes.

Service Ports

Component	Port
API	`3000`
STS	`8080`
Gateway	`8081`
Audit	`9090`
Coordinator	`4000`
Control	in-process in API (`3000`) when enabled

Production Values to Review

Area	Values
Images	`global.registry`, `global.tag`, `global.imagePullPolicy`, `global.mode`
Secrets	`secrets.runtimeSecretName`, `secrets.database.`, `secrets.redis.`, token secret refs
Network	`networkPolicy.`, `ingress.gateway.`, `ingress.api.*`
Reliability	`services.<name>.replicas`, `pdb`, `hpa`, resource requests/limits
Replay	`replayPersistence.enabled`, `storageClassName`, `size`
Observability	`serviceMonitor.enabled`, `alertRules.enabled`, `global.otelExporterOtlpEndpoint`

Validation Flow

helm lint infra/helm/caracal
helm template caracal infra/helm/caracal --values infra/helm/caracal/values.production.yaml >/tmp/caracal.yaml
kubectl -n caracal rollout status deploy/caracal-api
kubectl -n caracal get pods,svc

Run readiness probes through the Service or Ingress endpoints after rollout.

Rollback

helm -n caracal history caracal
helm -n caracal rollback caracal <revision>

Migrations are forward-only. Rollbacks must use application versions compatible with the already-applied schema.

Troubleshooting

Symptom	Check
Migration Job fails	Check database host, port, user, database name, password key, and `sslMode`.
Pods fail readiness	Inspect dependency readiness, mounted secrets, and service-specific required env vars.
Gateway Ingress works but upstream calls fail	Check NetworkPolicy egress and upstream allowlist configuration.
STS or Gateway loses audit replay	Ensure replay persistence is enabled and PVCs are not deleted during rollouts.

Next Step

Use Choose a Cloud Profile when the Helm deployment needs managed storage, ingress, external secrets, or production network policy.