Kubernetes Containers Monitoring

How to Deploy Sentry in Kubernetes Using Helm (Step-by-Step)

Deploy self-hosted Sentry on Kubernetes with the sentry-kubernetes Helm chart: values for ClickHouse, ingress, SMTP, Slack and PostgreSQL, then verify it.

Sentry is an open-source error-tracking and performance-monitoring platform. It captures exceptions and events from your applications and gives you a web UI to search, analyze, and fix issues. Running Sentry in Kubernetes with Helm lets you manage configuration as code and scale the web, workers, and dependencies (PostgreSQL, Redis, Kafka, ClickHouse) in one place. This guide walks you through adding the Sentry Helm repo, creating a custom values file (ingress, mail, Slack, external PostgreSQL and ClickHouse), installing with Helm or Helmfile, and verifying the deployment.

In this guide you’ll:

  • Add the official Sentry Helm repository and pull the latest chart
  • Create a custom values file for admin user, ingress (e.g. Traefik + cert-manager), SMTP (e.g. Resend), Slack, external PostgreSQL, and the external ClickHouse the chart now requires
  • Install Sentry into a dedicated namespace and optionally use Helmfile for declarative releases
  • Verify pods and access Sentry via ingress, LoadBalancer, or port-forward

Prerequisites

  • A Kubernetes cluster (e.g. EKS, AKS, GKE, k3s) with kubectl configured.
  • Enough capacity. The chart runs dozens of pods (web, Relay, Snuba, task workers, ingest consumers, Kafka, Redis, PostgreSQL). Sentry’s self-hosted docs list 4 CPU cores, 16 GB RAM (32 GB recommended) and 20 GB disk as the minimum for a single machine; plan for at least that much spare across your nodes. A small Minikube or kind cluster will not run it.
  • Helm 3.8 or later installed (helm version); 3.8+ is needed for the OCI install option below.
  • An external ClickHouse server. The bundled ClickHouse has been removed from the chart, so externalClickhouse is required (see the chart’s external services guide).
  • Persistent storage (a default StorageClass) for PostgreSQL, Kafka and Redis if you use the in-chart versions, or external instances of each.
  • (Optional) An Ingress controller (e.g. Traefik) or a Gateway API implementation, and cert-manager if you want TLS and a custom hostname.

Table of contents

1. Add the Sentry Helm repository

The official Sentry charts are maintained at sentry-kubernetes/charts. Add the repo and update it:

helm repo add sentry https://sentry-kubernetes.github.io/charts
helm repo update

Confirm the chart is available:

$ helm search repo sentry

NAME                     CHART VERSION APP VERSION DESCRIPTION
sentry/sentry            35.0.0        26.10.1     A Helm chart for Kubernetes
sentry/sentry-db         0.9.4         10.0.0      A Helm chart for Kubernetes
sentry/sentry-kubernetes 0.4.0         latest      A Helm chart for sentry-kubernetes (https://git...
sentry/clickhouse        4.1.1         23.8.16.16  ClickHouse is an open source column-oriented da...

These are the versions current at the time of writing (chart 35.0.0, Sentry 26.10.1); your output will show whatever is newest. The chart is also published as an OCI artifact on GHCR, so you can skip helm repo add and install from oci://ghcr.io/sentry-kubernetes/charts/sentry --version <chart-version>.

2. Create a custom values file

Download the default values to use as a base:

helm show values sentry/sentry > values.yaml

Then create a custom values file (e.g. sentry-values.yaml) and override only what you need. Do not commit real passwords or secrets to Git—use placeholders and inject them via --set, --set-file, or a secrets manager.

Example overrides (replace placeholders and hostnames with your own):

user:
  create: true
  email: [email protected]
  # Either password or existingSecret is required when create is true
  existingSecret: sentry-admin-password # Secret with key "admin-password"
  # password: "CHANGE_ME_STRONG_PASSWORD"

ingress:
  enabled: true
  regexPathStyle: traefik
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod-issuer
  hostname: sentry.example.com
  tls:
    - hosts:
        - sentry.example.com
      secretName: sentry-tls

sentry:
  singleOrganization: false
  # Background jobs now run on taskbroker/taskworker (sentry.worker is gone)
  taskWorker:
    replicas: 1

system:
  url: "https://sentry.example.com"
  adminEmail: "[email protected]"
  public: true
  # secretKey: "..."  # set when upgrading to preserve sessions

mail:
  backend: smtp
  useTls: true
  username: "your-smtp-user"
  password: "your-smtp-password"
  port: 587
  host: "smtp.example.com"
  from: "[email protected]"

# Optional: Slack integration — create a Slack app for credentials
# https://develop.sentry.dev/integrations/slack/
slack:
  clientId: "xxxx.xxxx"
  clientSecret: "xxxx"
  signingSecret: "xxxx"

postgresql:
  enabled: false

# Required when postgresql.enabled is false
externalPostgresql:
  host: postgres.database.svc.cluster.local
  port: 5432
  username: sentry
  password: "your-db-password" # or existingSecret + existingSecretKeys.password
  database: sentry

# Required: the chart no longer bundles ClickHouse
externalClickhouse:
  host: clickhouse.clickhouse.svc.cluster.local
  tcpPort: 9000
  httpPort: 8123
  username: default
  password: "your-clickhouse-password" # or existingSecret
  database: default
  singleNode: true

Summary of what these do:

  • user: Initial admin user created on first install. The chart refuses to install without user.password or user.existingSecret; the Secret is the safer choice.
  • ingress: Expose Sentry via Traefik (or another Ingress class) with TLS (e.g. cert-manager). regexPathStyle: traefik tells the chart to render Traefik-style regex paths so ingestion (/api/<id>/...) goes to Relay and everything else to the web service. Setting annotations replaces the chart’s nginx defaults, which is what you want for Traefik.
  • system: Public URL and admin email; required for links in emails and the UI.
  • mail: SMTP for outgoing email (e.g. Resend, SendGrid, or your own server).
  • slack: Slack app credentials for alert notifications (optional).
  • externalPostgresql: Use an existing PostgreSQL instance instead of the chart’s built-in Postgres.
  • externalClickhouse: Where Snuba stores events. Required since the bundled ClickHouse was removed.

The chart supports four mutually exclusive ways to expose Sentry, all off by default; enable exactly one:

  • ingress.enabled — a standard Kubernetes Ingress (shown above).
  • traefikIngressRoute.enabled — a Traefik IngressRoute CRD instead of an Ingress.
  • route.main.enabled — a Gateway API HTTPRoute (set hostnames and parentRefs).
  • nginx.enabled — an in-cluster nginx reverse proxy Service you can expose as a LoadBalancer.

If you are on ingress-nginx, note that Kubernetes retired the project (best-effort maintenance ended in March 2026), so Traefik or Gateway API is the better long-term choice for new installs.

3. Deploy Sentry with Helm

Create the namespace and the admin password Secret referenced by user.existingSecret, then install the chart (use the same values filename you created):

kubectl create namespace sentry
kubectl create secret generic sentry-admin-password -n sentry \
  --from-literal=admin-password='CHANGE_ME_STRONG_PASSWORD'

helm install sentry sentry/sentry \
  --namespace sentry \
  --version 35.0.0 \
  -f ./sentry-values.yaml \
  --wait --timeout=1000s

Use a specific chart version (e.g. 35.0.0) for reproducible installs. The first install runs database and Snuba migration jobs as Helm hooks, which is why the chart docs use a long --timeout. If you would rather not create a Secret, pass the password at install time with --set user.password="YourPassword", but note Helm stores supplied values in its release metadata.

4. Optional: Use Helmfile

Helmfile lets you manage Helm releases as code. Create helmfile.yaml:

helmDefaults:
  createNamespace: true
  timeout: 1000
  wait: true

repositories:
  - name: sentry
    url: https://sentry-kubernetes.github.io/charts

releases:
  - name: sentry
    namespace: sentry
    chart: sentry/sentry
    version: "35.0.0"
    values:
      - ./sentry-values.yaml

Preview rendered manifests, then sync:

helmfile template
helmfile sync

5. Verify the deployment

Check that pods are running:

kubectl get pods -n sentry

You should see pods for the Sentry web frontend, Relay, Snuba, the taskbroker/taskworker/taskscheduler, the ingest consumers, and (if enabled) PostgreSQL, Redis, and Kafka. Wait until they are Running and ready. If any stay in Pending or CrashLoopBackOff, check kubectl describe pod <name> -n sentry and the chart’s requirements (e.g. external PostgreSQL and ClickHouse reachable, correct credentials, enough CPU and memory to schedule every pod).

6. Access Sentry

  • If you configured Ingress: Open the URL you set in system.url / ingress.hostname (e.g. https://sentry.example.com) and log in with the user.email and user.password from your values.
  • If using a LoadBalancer: Enable nginx.enabled and set nginx.service.type=LoadBalancer, then run kubectl get svc -n sentry and use the external IP of the *-nginx service. It routes the UI to sentry-web and ingestion to Relay.
  • For local testing: Port-forward the web service:
kubectl port-forward -n sentry svc/sentry-web 9000:9000

Then open http://localhost:9000 and log in. This reaches the UI only; SDK events go to Relay, so use a real ingress or route before pointing applications at it.

7. Post-deployment setup

  • Complete the setup wizard in the Sentry UI (organization name, etc.).
  • Confirm email (SMTP) works from Sentry settings if you use notifications or password reset.
  • Create projects and install the Sentry SDK in your applications (e.g. Python, Node, Go) using the DSN provided by Sentry.
  • Optionally add team members and configure Slack (or other integrations) for alerts.

Frequently Asked Questions (FAQ)

What is Sentry?

Sentry is an error-tracking and performance-monitoring platform. It captures exceptions, errors, and performance data from your applications and surfaces them in a web UI so you can debug and fix issues quickly. It supports many languages and frameworks and can be self-hosted (as in this guide) or used as a hosted service.

Can I use the built-in PostgreSQL instead of external?

Yes. Set postgresql.enabled: true (the default) in your values and remove or leave empty the externalPostgresql block. The chart will deploy PostgreSQL in the cluster (Redis and Kafka are bundled by default either way). Ensure your cluster has a default StorageClass for persistent volumes. The chart docs recommend external PostgreSQL, Redis and Kafka for production; the bundled ones are meant for testing. ClickHouse has no bundled option any more.

How do I upgrade Sentry after deployment?

Back up your database, read the chart’s upgrade guide before crossing a major chart version, then run helm upgrade sentry sentry/sentry -n sentry -f ./sentry-values.yaml --version <new-version> --wait --timeout=1000s. The Sentry secret key is generated on first install and kept in a Kubernetes Secret; to manage it yourself (for example with Argo CD, where each render would otherwise generate a new key), point sentry.existingSecret / sentry.existingSecretKey at a Secret you control.

Where can I find the Sentry Helm chart values reference?

Run helm show values sentry/sentry for the full default values. The chart source and documentation are in sentry-kubernetes/charts.

Conclusion

You deployed Sentry on Kubernetes using the official Helm chart: added the Sentry repo, created a custom values file (admin user, Ingress, mail, Slack, external PostgreSQL and ClickHouse), installed with helm install or Helmfile, and verified pods and access. Use strong passwords and avoid committing secrets to Git; prefer --set or a secrets manager for sensitive values. To put TLS in front of the Ingress, see how to configure Ingress TLS/SSL certificates in Kubernetes; to add tracing alongside Sentry’s error data, see OpenTelemetry explained. For more on Kubernetes and observability, see other guides on monitoring and Kubernetes on this site.

comments powered by Disqus
© 2020 - 2026 Citizix, Ltd.
Citizix Ltd
Built with Hugo
Theme Stack designed by Jimmy