---
title: "Deploy with Helm"
url: "https://docs.caracal.run/operations/kubernetes-helm/"
markdown_url: "https://docs.caracal.run/markdown/operations/kubernetes-helm.md"
description: "Deploy Caracal on Kubernetes with the repository Helm chart."
page_type: "workflow"
concepts: []
requires: []
---

# Deploy with Helm

Canonical URL: https://docs.caracal.run/operations/kubernetes-helm/
Markdown URL: https://docs.caracal.run/markdown/operations/kubernetes-helm.md
Description: Deploy Caracal on Kubernetes with the repository Helm chart.
Page type: workflow
Concepts: none
Requires: none

---

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

```bash
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](/operations/cloud-reference-deployments/).

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

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

```bash
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](/operations/cloud-native-profiles/) when the Helm deployment needs managed storage, ingress, external secrets, or production network policy.