feat: add OpenShift / OKD support (Route template + deployment guide) - #344
feat: add OpenShift / OKD support (Route template + deployment guide)#344lokeshrangineni wants to merge 3 commits into
Conversation
Adds first-class support for deploying Langfuse on OpenShift and OKD clusters.
Changes
-------
- charts/langfuse/templates/route.yaml
New template that renders an `route.openshift.io/v1` Route resource when
`langfuse.route.enabled: true`. Mirrors the existing ingress.yaml pattern
and supports edge, reencrypt, and passthrough TLS termination modes.
- charts/langfuse/values.yaml
New `langfuse.route` section with `enabled`, `host`, `annotations`,
`additionalLabels`, and full TLS options (termination, policy, certs).
Disabled by default; does not affect existing Kubernetes deployments.
- charts/langfuse/tests/route_test.yaml
8 helm-unittest test cases covering: disabled (default), auto-generated host,
explicit host, edge TLS (default), passthrough TLS, TLS disabled,
custom annotations/labels, and mutual exclusion with ingress.
- examples/openshift/
Step-by-step deployment guide (README.md), annotated values file
(values.yaml), and secret template (secret.yaml).
- TROUBLESHOOTING.md
New section documenting the Bitnami SCC conflict with OpenShift's
restricted-v2 policy, with two remediation paths (see below).
Known limitation — Bitnami sub-charts and OpenShift SCCs
---------------------------------------------------------
The bundled PostgreSQL and Valkey/Redis sub-charts use Bitnami images that
run as a fixed UID (1001). OpenShift's default restricted-v2 SCC enforces
a namespace-allocated UID range and rejects this fixed UID, causing pods to
fail at startup.
Two options are documented in examples/openshift/ and TROUBLESHOOTING.md:
Option A (dev/demo clusters only):
Grant anyuid SCC to the chart service account:
oc adm policy add-scc-to-user anyuid -z <release-name> -n <namespace>
This bypasses UID isolation and is NOT recommended for production.
Option B (recommended for production):
Disable the bundled PostgreSQL sub-chart (`postgresql.deploy: false`)
and provision an SCC-compliant PostgreSQL instance — e.g. via the
CrunchyData PGO operator (available in OperatorHub) or any managed
service. This removes the Bitnami dependency entirely.
A follow-up contribution to add a CrunchyData PGO example is planned.
Tested on OpenShift 4.20 (ai-dev02.kni.syseng.devcluster.openshift.com).
All 69 existing helm-unittest tests continue to pass; 8 new route tests added.
Made-with: Cursor
…P 4.20
Fixes discovered during actual deployment on OpenShift 4.20:
- secret.yaml: add missing clickhouse-password key (Langfuse v3 requires
ClickHouse; omitting this key causes helm install to fail with
"Configuring an existing secret or clickhouse.auth.password is required")
- values.yaml: remove podSecurityContext.runAsNonRoot: true from Langfuse
web/worker section — the image uses a non-numeric user ("nextjs") which
causes CreateContainerConfigError on OpenShift; leave podSecurityContext: {}
and rely on the anyuid SCC grant instead
- values.yaml: add missing clickhouse.auth.existingSecret wiring
- README.md: grant anyuid to both 'langfuse' and 'default' service accounts
(ClickHouse uses the default SA); add note about non-numeric user issue;
use alphanumeric-only DB passwords to avoid ClickHouse special-char bug
Made-with: Cursor
|
|
dosubot
Bot
added
the
size:L
|
@deejay1 or @MrOrz or @Steffen911 - Could you help me to review the PR and provide any feedback. I am happy to make any changes if it is needed. |
|
@lokeshrangineni As far as I can tell, openshift already supports the Ingress resource (https://docs.redhat.com/en/documentation/openshift_container_platform/4.9/html/networking/configuring-ingress) and translates it to a route internally. What's the added benefit of bringing this PR in aside from additional documentation on openshift? |
Hi @Steffen911, thanks for the review. You're right that OpenShift's Ingress controller auto-translates Ingress into Route objects, so a native Route template alone wouldn't justify this PR. The main motivation is the SCC (Security Context Constraints) pain point, which is the real blocker for deploying Langfuse on OpenShift today:
These issues took real debugging time on OCP 4.20. The TROUBLESHOOTING.md and examples/openshift/ sections document two remediation paths (anyuid SCC for dev, external PostgreSQL via CrunchyData PGO for production) so future OpenShift users don't hit the same walls. The native Route template is a small addition on top — it's disabled by default with zero impact on existing deployments. Happy to adjust the scope if needed! |
|
In that case, let's separate the route behaviour from the debugging assistance. I'm happy to merge the additional troubleshooting information, but would like to see upvotes or engagement from the wider community before adding the route into the helm chart. |
3 participants
Summary
Adds support for deploying Langfuse on OpenShift / OKD clusters, which use
Routeresources instead ofIngressand enforce pod security via Security Context Constraints (SCCs).Changes
charts/langfuse/templates/route.yaml— newroute.openshift.io/v1Route template, disabled by default (langfuse.route.enabled: false), supportsedge,reencrypt, andpassthroughTLS terminationcharts/langfuse/values.yaml— newlangfuse.routesection (host, TLS options, annotations, labels)charts/langfuse/tests/route_test.yaml— 8 helm-unittest tests; all 69 existing tests still passexamples/openshift/— step-by-step README, annotated values.yaml, and secret template validated on OCP 4.20TROUBLESHOOTING.md— new section on Bitnami SCC conflict with two remediation pathsKnown Limitation — Bitnami sub-charts and OpenShift SCCs
Bitnami images (PostgreSQL, Redis, ClickHouse) run as fixed UID
1001, which conflicts with OpenShift'srestricted-v2SCC. Two options documented:anyuidSCC to thelangfuseanddefaultservice accountspostgresql.deploy: false) via CrunchyData PGO operator — eliminates the Bitnami dependency entirelyThis is a limitation of the upstream Bitnami images, not the Langfuse chart itself.
Test plan
Made with Cursor