cairnobs/deploy/helm/sentry/README.md

deploy/helm/sentry

A Helm chart covering every docker-compose.yml service (Redpanda, ClickHouse, Postgres, ingest, search, alerting, web) plus, when enterprise.enabled: true: enterprise-auth, the deploy/operator tenant-operator, and Tenant CRs from values.tenants. See /deploy/README.md for what "multi-tenant-aware" does and doesn't mean at this layer, and its verification-status section before trusting this against a real cluster.

This chart never builds images -- push every image its values.yaml references to a registry the cluster can pull from first, same division of labor as docker compose build vs. docker compose up.

api vs enterprise-api: one Deployment, chosen by enterprise.enabled

templates/api.yaml and templates/enterprise-api.yaml are mutually exclusive, gated on opposite sides of the same enterprise.enabled flag -- exactly one of them ever renders, both under the same {{ .Release.Name }}-api Service name and port 8080. This is the fix for what /docs/security/threat-model.md named as Phase 4's single largest remaining gap once both storage engines' isolation mechanisms were built: previously nothing forced or even flagged whether a deployment ran the tenant-isolated binary. Now it's not a second knob to remember -- the same flag that turns on RBAC/audit/SSO also swaps which query binary actually serves /query and /dashboards traffic. Every consumer (alerting's API_QUERY_URL, web's build args) needs zero conditional logic of its own, since both variants answer on the same name/port.

enterprise-api starts with an empty tenant set until -provision-tenant has been run for at least one tenant (see /enterprise/README.md) -- until then it's up and healthy, but every /query request correctly fails closed with no tenant to route to.

Startup ordering

docker-compose.yml uses depends_on: condition: service_healthy / service_completed_successfully to sequence startup (e.g. api waits for clickhouse-migrate to actually finish, not just for clickhouse to be reachable). This chart approximates that more loosely:

• Migration Jobs (clickhouse-migrate, metadata-migrate, redpanda-provision) are plain Job resources (not Helm hooks -- making the StatefulSets they depend on into hooks too, to get ordering, would break helm upgrade/helm uninstall's normal ownership tracking of stateful resources, a worse tradeoff), with backoffLimit: 6 so they retry a few times if their dependency isn't up yet.
• App Deployments get an initContainer that busy-waits for their dependency's TCP port, not for a specific Job's completion (see templates/_helpers.tpl's sentry.waitForTCP) -- this covers "is ClickHouse/Postgres/Redpanda up" but not "has the migration Job actually finished."
• The gap that leaves (a pod starts before its migration has completed) is covered by every Go service here already calling os.Exit(1) on a failed startup DB ping (see e.g. api/cmd/api/main.go) -- Kubernetes' pod restart policy retries with backoff until the schema is ready. This is a real, working, but looser guarantee than docker-compose's explicit ordering -- documented here rather than implied to be equivalent.

Trying the two-tenant example

# Quote each --set value -- zsh globs an unquoted tenants[0] as a
# pattern and fails with "no matches found." Also note: no --include-crds
# here -- that's a helm template-only flag (install always installs
# crds/ by default); confirmed the hard way running this against a real
# kind cluster, see /docs/phase-4-runbook.md §7.
helm install sentry . \
  --set enterprise.enabled=true \
  --set tenantOperator.enabled=true \
  --set 'tenants[0].name=acme' --set 'tenants[0].displayName=Acme Corp' \
  --set 'tenants[1].name=globex' --set 'tenants[1].displayName=Globex Corporation'

kubectl get tenants
# expect: both Provisioning -- the Tenant CRs above are just a
# declarative request; nothing has actually provisioned ClickHouse for
# either yet (see below).

kubectl exec -it deploy/sentry-api -- /enterprise-api -provision-tenant=acme -display-name="Acme Corp"
kubectl exec -it deploy/sentry-api -- /enterprise-api -provision-tenant=globex -display-name="Globex Corporation"

kubectl get tenants
# expect: both Active now.
kubectl get secret sentry-tenant-acme-clickhouse sentry-tenant-globex-clickhouse

Before any of this: ingest needs a real mTLS cert Secret (--set ingest.tlsSecretName=..., see values.yaml's comment on it and /docs/phase-4-runbook.md §7 for the exact kubectl create secret invocation using hack/dev-certs) or it crash-loops on startup -- unconditional by design, no disable switch.

Genuinely run against a real kind cluster, not just described: see /docs/phase-4-runbook.md §7 for the exact steps (image loading into kind, the two chart bugs it found and fixed) and confirmation that both tenants reached status.phase: Active with real credentials.

This proves Phase 4's "two tenants... with their own users, roles, dashboards" exit criteria (/CLAUDE.md) end to end at the deployment- topology layer: -provision-tenant (enterprise/internal/ tenantprovision) is what actually creates each tenant's ClickHouse database/user/grant and marks it active in rbacstore; running inside the enterprise-api Deployment's Pod means it automatically syncs that real result into the Tenant CRD too (enterprise/internal/tenantcrd, via the ServiceAccount/Role tenantOperator.enabled also grants that Deployment) -- the credential Secret you see above has real credentials, not a placeholder, and Tenant.status.phase: Active means the same thing rbacstore.tenants.status='active' does, not two different claims about two different systems. The Tenant CRD and -provision-tenant used to be genuinely disconnected (a Secret existed the moment the CR was created, with a password that authenticated against nothing) -- see /deploy/README.md's "lightweight unification" section for the full history. OIDC/SAML login still needs a manual tenant_memberships grant (enterprise-auth -grant-membership-* -- see /docs/phase-4-runbook.md §3a/§3b) before a human can actually query as either tenant.

web's image needs rebuilding per environment

web is a static SvelteKit build (adapter-static) -- its three API base URLs (VITE_API_BASE_URL/VITE_ALERTING_API_BASE_URL/ VITE_ENTERPRISE_AUTH_BASE_URL) are baked in at image build time (web/Dockerfile's build args), not read from the container's environment at runtime. values.yaml's web.builtWithApiBaseURL etc. document what the image you point web.image at needs to have been built with (an Ingress hostname, a LoadBalancer IP, etc.) -- this chart has no Ingress resources and can't itself act on those values; rebuild web's image with the right build args for wherever this release is actually reachable from a browser before pointing real users at it.

Validating without a cluster

helm lint .
helm template sentry . --include-crds > /tmp/rendered.yaml

See /deploy/README.md's verification section for what was checked this way versus against a real cluster (now done -- see above).