# Sentry Helm charts: deploying crash reporting, and the ClickHouse behind it

> The sentry-kubernetes/charts repository is the Helm packaging for a self-hosted Sentry, and its README spends most of its length on a single hard-won detail: the ClickHouse that Sentry needs is now better run by an operator than by the bundled chart, and getting the operator's configuration to stick requires a values file rather than a --set flag.

**sentry-kubernetes/charts** — Easily deploy Sentry on your Kubernetes Cluster

- Repository: https://github.com/sentry-kubernetes/charts
- Stars: 1,384 · Forks: 592
- Language: Mustache
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/sentry-kubernetes-charts

## What the charts package, and what they assume

The repository is a set of Helm charts whose purpose is stated in one line: easily deploy Sentry on your Kubernetes cluster. Sentry itself is a cross-platform crash reporting and aggregation platform, and the charts package the server, its workers and the stateful dependencies it needs.

The releases are named after the Sentry version they package, `sentry-v33.8.0`, `sentry-v33.7.0` and `sentry-v33.6.0` in August 2026, which is a convention worth knowing because it means the chart version and the Sentry version are not the same number, and a mismatch between them is a common source of confusion.

The language of the repository is Mustache, which tells you the shape of the thing: these are Helm templates, not an application. The `charts/` directory holds the charts themselves, each with its own `README.md` in its directory carrying the values and configuration instructions for that chart, and the `docs/` directory holds the material that is not specific to one chart.

The assumption the charts make is that you have a Kubernetes cluster and a Helm client, and that you are willing to run a stateful database. The documentation is written for a production installation rather than a trial, and the difference shows in the numbers: three ClickHouse replicas, three Keeper nodes, explicit storage requests, and pod anti-affinity so that the replicas land on different nodes.

The repository also carries the tooling that keeps it tidy: a `release-please` configuration with its manifest, which is what cuts the versioned chart releases, a `renovate.json` for dependency updates, and a `CHANGELOG.md` with the upgrade instructions and the version history.

## The bundled ClickHouse is legacy, and the operator is the recommendation

The most important paragraph in the README is the short one at the top, and it changes the shape of the installation.

Bundled ClickHouse chart dependencies are legacy and may receive limited updates, and it is recommended to use an externally managed ClickHouse deployment, such as the Altinity ClickHouse Operator. The bundled dependency still works, and the charts still install it, but the project is steering people away from it, which in practice means the documented path has three external steps before Sentry itself is installed.

The first step is the operator, and the values file matters more than the command:

```bash
helm repo add clickhouse-operator https://helm.altinity.com
helm repo update
helm upgrade --install clickhouse-operator clickhouse-operator/altinity-clickhouse-operator \
  --version 0.26.0 \
  --namespace clickhouse-operator \
  --create-namespace \
  -f clickhouse-operator-values.yaml \
  --wait
```

The values file contains a watch configuration with the `sentry` namespace, so the operator knows which ClickHouse installations it should manage. And the README carries a warning that is worth more than the command it accompanies: do not use `--set 'configs.files.config.yaml.watch.namespaces={sentry}'`, because Helm interprets dots as nested keys, which creates a separate `config` file instead of modifying `config.yaml`, causing the operator to ignore the setting.

That is a classic Helm trap, and the reason the documentation tells you to check that the operator is running at all, with a `kubectl get pods` filtered on the operator's own labels. An operator that is up but watching nothing will install ClickHouse and then leave it unmanaged, and the symptom appears much later, when the data does not arrive where Sentry expects it.

## Keeper and ClickHouse are custom resources, not Helm values

The second and third steps install the stateful part, and they are the part of the README that will look unfamiliar to somebody who has only deployed stateless services.

Step two is ClickHouse Keeper, and the manifest is a `ClickHouseKeeperInstallation` custom resource. The production recommendation is a high availability cluster with three ClickHouse replicas and three ClickHouse Keeper nodes, with a separate document for single-node testing. The Keeper manifest defines a cluster named `keeper-cluster`, a pod template and a volume claim template, and the interesting part of the spec is the affinity, which requires pod anti-affinity on a label selector so the three Keeper pods do not land on the same node. The storage request is 10Gi per node.

Step three is ClickHouse itself, a `ClickHouseInstallation` custom resource with a cluster of one shard and three replicas, a volume claim template asking for 20Gi, and the same anti-affinity pattern. The `zookeeper` section points at the three Keeper pods by their generated service names and port 2181, and the defaults set `replicasUseFQDN` to yes so that the replicas address each other by their fully qualified names rather than by a short service name.

The order of operations is enforced by the operator rather than by Helm. The Keeper manifest is applied first and the three pods are watched until they are ready, and the ClickHouse manifest is applied afterwards and watched with `kubectl get chi sentry-clickhouse -w` until the `status.status` field shows `Completed` and the pods are `Running`. So the ClickHouse installation is a reconciliation loop that the operator completes, and a Sentry install started before that point will be pointed at a database that does not exist yet.

## Service names, cluster names, and the values file

Step four and step five are where the installation is connected together, and the connecting is a matter of names.

Step four creates the secret that holds the Sentry admin password, and it is a plain Kubernetes secret created with a literal value in the `sentry` namespace, with the chart then told to use it through the `user.existingSecret` key.

Step five starts by finding the ClickHouse service the operator created, because the Sentry values file needs the host name and the operator's naming convention is not obvious. There are two names, and the README lists both: `clickhouse-sentry-clickhouse`, the main load-balanced service, and `chi-sentry-clickhouse-single-node-0-0`, a per-pod service for shard zero, replica zero.

The values file is then written with the external ClickHouse section:

```yaml
user:
  existingSecret: sentry-admin-password
externalClickhouse:
  host: "clickhouse-sentry-clickhouse.sentry.svc.cluster.local"
  tcpPort: 9000
  httpPort: 8123
  username: "default"
  password: ""
  database: "default"
  singleNode: false
  clusterName: "sentry-cluster"
```

And there is a note that has bitten people: the `clusterName` in the Sentry values file must match the cluster name in the ClickHouse manifest, which is `sentry-cluster` in the example. Two manifests written by hand, with a string that has to agree, and no validation that the string is a name of anything that exists.

The two ports are the native protocol port and the HTTP port, and both are needed because Sentry speaks to ClickHouse over the native protocol for the heavy queries and over HTTP for the rest.

## Two install paths, one long timeout

The Sentry chart itself is installed in one of two ways, and both are in the README.

From the Helm repository:

```bash
helm repo add sentry https://sentry-kubernetes.github.io/charts
helm repo update
helm install -n sentry my-sentry sentry/sentry -f values.yaml --wait --timeout=2400s
```

Or from GHCR over OCI, which is the path the README recommends for a Harbor proxy cache:

```bash
helm install -n sentry my-sentry oci://ghcr.io/sentry-kubernetes/charts/sentry --version <chart-version> -f values.yaml --wait --timeout=2400s
```

Two details in those commands carry weight. The timeout is 2400 seconds, which is forty minutes, and it is not optimism, it is the Sentry image pulling, migrating and warming up during the install, and a shorter timeout turns a slow successful install into a failed one. And the OCI variant takes an explicit chart version, which is a good habit for a chart whose version numbers track the Sentry release inside it.

The `values.yaml` is the only file you are expected to write. The README is explicit that each chart has its own `README.md` with the values and configuration instructions, for example in `charts/sentry/README.md`, so the documentation is per chart rather than only at the root, and the root `CHANGELOG.md` is where the upgrade instructions and the version history live.

## PostgreSQL, and where these charts stop being the right answer

The last configuration topic in the visible part of the README is the other stateful dependency, and it is simpler than ClickHouse.

By default, PostgreSQL is installed as part of the chart. To use an external PostgreSQL server, set `postgresql.enabled` to `false` and then set `postgresql.postgresHost` and `postgresql.postgresqlPassword`, with the other options such as the database name and the username alongside them.

That is the whole of the stateful configuration, and the fact that it takes four lines rather than forty is the point: ClickHouse is hard because of the operator and the custom resources and the three-node Keeper, and PostgreSQL is easy because the chart can install a single instance for you.

With that in place, it is worth being clear about when these charts are the wrong tool. A team that wants error tracking without operating it should use the hosted service, and the entire chart, the ClickHouse, the Keeper, the secret and the 40 minute timeout are cost without benefit. A team that wants a self-hosted Sentry for a handful of internal applications is also paying more than it needs to, because the default installation brings a database and a cache along with it.

The alternative approach, for a team that has decided to self-host but does not want to run stateful workloads on Kubernetes, is the self-hosted installation with a managed database, and the difference in approach is that these charts assume you own the whole cluster including the databases, while the alternative assumes you own only the application and rent the rest. Both are defensible, and the decision is mostly about who is going to be paged when ClickHouse falls over.

## Conclusion

The Sentry charts fit a team that has decided to run its own error tracking, that has Kubernetes to run it on, and that is prepared to operate ClickHouse and Keeper as separate stateful workloads rather than as a bundled subchart. It is the wrong choice for a team that wants a hosted service, and it is a heavy choice for a team that only needs a small self-hosted instance, because the default installation drags in PostgreSQL, ClickHouse and Keeper. Before installing, read the external ClickHouse section in full rather than following the default path, set `postgresql.enabled` to false if you already have a database, and check the `CHANGELOG.md` for the chart version you are pinning, because the chart versions track the Sentry release they package.

## FAQ

### How do I install the Sentry Helm chart?

Add the repo with `helm repo add sentry https://sentry-kubernetes.github.io/charts`, run `helm repo update`, then `helm install -n sentry my-sentry sentry/sentry -f values.yaml --wait --timeout=2400s`. An OCI variant is published at oci://ghcr.io/sentry-kubernetes/charts/sentry with a `--version` flag, and the README notes that Harbor proxy caches need that path.

### Why does the Sentry chart recommend an external ClickHouse?

Because the bundled ClickHouse chart dependencies are legacy and may receive limited updates, so the documentation recommends an externally managed deployment such as the Altinity ClickHouse Operator, with three ClickHouse replicas and three Keeper nodes for production.

### How do I use an external PostgreSQL with the Sentry chart?

Set `postgresql.enabled` to `false` and then set `postgresql.postgresHost` and `postgresql.postgresqlPassword`, with the other options such as the database name and the username alongside them, since by default PostgreSQL is installed as part of the chart.

### Why is my --set flag for the ClickHouse operator ignored?

Because Helm interprets dots in a --set value as nested keys, so the setting creates a separate config file instead of modifying config.yaml, and the operator then ignores it. The documentation uses a values file containing the watch namespaces list instead.

## Sources

- [Issues](https://github.com/sentry-kubernetes/charts/issues)
- [License: MIT](https://github.com/sentry-kubernetes/charts/blob/develop/LICENSE)
- [README](https://github.com/sentry-kubernetes/charts/blob/develop/README.md)
- [Releases](https://github.com/sentry-kubernetes/charts/releases)
- [sentry-kubernetes/charts on GitHub](https://github.com/sentry-kubernetes/charts)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sentry-kubernetes-charts