OKDP Superset is a packaging of Apache Superset for Kubernetes: a custom Docker image and a Helm chart that wraps the official Apache Superset chart with OAuth2/OIDC providers (Keycloak, Dex), optional OAuth2 for Trino, and externalized Kubernetes Secrets.
The upstream Apache Superset Helm chart deploys Superset, but several integrations have to be implemented from scratch on every install:
- OAuth2/OIDC requires custom Python code. Wiring Keycloak or Dex means writing a
CustomSsoSecurityManagerand injecting it viaconfigOverrides. - The official Docker image does not bundle Trino, PostgreSQL drivers or
Authlib. They have to be installed at deploy time or in a custom image. - Secrets live in
values.yaml. Database, Redis, OAuth2 and Superset secrets are not separated into dedicated Kubernetes Secrets. - No Trino OAuth2 wiring. The Superset
DATABASE_OAUTH2_CLIENTSsetting is not exposed by the chart.
OKDP Superset adds a thin layer on top that ships these integrations as defaults:
- Ready-to-use Keycloak and Dex providers in the chart.
apache-superset[trino,postgres]andAuthlibpre-installed in the image.- Database, Redis, OAuth2, Superset and Trino OAuth2 credentials each in their own Kubernetes Secret.
- Optional OAuth2 client wiring for a Trino datasource.
- Weekly automated rebuild of the latest release tag to pick up base-image security patches.
This repository builds and publishes:
- A Docker image based on
apache/supersetwith extra Python dependencies pre-installed —apache-superset[trino,postgres]>=6.0.0,<7.0.0andAuthlib(docker/requirements.txt). - Security-patched rebuilds of the upstream
-dockerizeand-websocketimage variants used as init and websocket sidecars by the chart. - A Helm chart that wraps the official Apache Superset chart (
helm/superset/Chart.yamldepends onsuperset0.15.2) and adds the OKDP defaults listed in Why this project.
The diagram below shows the components that a helm install of this chart creates inside a Kubernetes cluster, plus the external services Superset can be wired to (an OAuth2/OIDC IdP and a Trino coordinator). For the upstream Superset runtime design (Flask, Celery, Redis as broker, metadata DB), see the official Apache Superset documentation.
A helm install creates the Superset web Deployment, the Celery worker Deployment, plus an embedded PostgreSQL (helm/superset/values.yaml#L1106) and Redis (helm/superset/values.yaml#L1151). Both can be disabled to bring your own (superset.postgresql.enabled: false / superset.redis.enabled: false). External IdPs (Keycloak, Dex) and the Trino coordinator are reached over the network; the chart wires the corresponding env vars and Python configOverrides for you.
- A Kubernetes cluster with a default
StorageClassproviding dynamic PV provisioning (the bundled PostgreSQL and Redis subcharts request PVCs by default). - Helm
>= 3. opensslto generate the Flask secret key in Quick Start.
| Tool | Version |
|---|---|
| Kubernetes (Kind) | 1.30.0 |
| Kind | 0.23.0 |
| Helm CLI | 3.18.4 |
| kubectl | 1.33.2 |
| Docker | 28.2.2 |
helm upgrade --cleanup-on-fail --install my-release \
oci://quay.io/okdp/charts/superset --version 0.15.2-2.0 \
--set okdp.superset.superset_secret_key=$(openssl rand -base64 42)
okdp.superset.superset_secret_keyis used by Flask to sign session cookies and encrypt sensitive data in the Superset metadata DB. Generate a strong unique value withopenssl rand -base64 42and treat it as a long-lived secret. Replace0.15.2-2.0with the latest released chart version.
kubectl get pods
# NAME READY STATUS RESTARTS AGE
# my-release-postgresql-0 1/1 Running 0 2m
# my-release-redis-master-0 1/1 Running 0 2m
# my-release-superset-<hash> 1/1 Running 0 2m
# my-release-superset-init-db-<hash> 0/1 Completed 0 2m
# my-release-superset-worker-<hash> 1/1 Running 0 2mA few RESTARTS on my-release-superset-* and my-release-superset-worker-* are normal on a resource-constrained cluster (laptop, kind) — the liveness/readiness probes have aggressive timeouts and may fail under load. As long as the pods reach READY 1/1 and /health returns 200, the release is healthy.
Port-forward the Superset web service and check the health endpoint:
kubectl port-forward svc/my-release-superset 8088:8088
curl -sL -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/health
# 200Open http://127.0.0.1:8088 and log in with the default admin user (admin / admin, helm/superset/values.yaml#L1030-L1036). Change the password immediately, or enable OAuth2 (see Configuration).
A ready-to-use values file is provided at helm/superset/sample-values.yaml — Keycloak OAuth2, nginx Ingress with cert-manager (Let's Encrypt staging), examples loading at install time.
helm upgrade --cleanup-on-fail --install my-release \
oci://quay.io/okdp/charts/superset --version 0.15.2-2.0 \
--values helm/superset/sample-values.yamlA complete reference of the chart values is available in the Helm chart README, auto-generated from helm/superset/values.yaml by helm-docs.
The chart exposes two top-level value sections:
okdp:— OKDP-specific high-level configuration, summarised below.superset:— passthrough to the upstreamsupersetsubchart; any upstream value can be set under this prefix.
The most important OKDP-specific keys (full reference in helm/superset/values.yaml and the Helm chart README):
| Key | Default | Description |
|---|---|---|
okdp.superset.superset_secret_key |
(insecure placeholder — override) | Flask session cookie signing key. |
okdp.superset.load_examples.enabled |
false |
If true, the init Job loads the upstream Superset example dashboards. |
okdp.oauth.enabled / okdp.oauth.provider |
false / "" |
Toggle OAuth2/OIDC and pick keycloak or dex. |
okdp.oauth.base_url / client_id / client_secret / scope |
— | OAuth2/OIDC client parameters. |
okdp.oauth.oauth2_superset_roles_mapping |
(empty) | Map IdP groups/roles to Superset roles. |
okdp.trino.oauth.enabled |
false |
Enable OAuth2 for the Trino datasource. |
Upstream Apache Superset chart values (e.g. superset.image, superset.ingress, superset.init.adminUser, superset.postgresql.enabled, superset.redis.enabled) are passed through to the official subchart.
All artefacts are published under quay.io/okdp:
| Artefact | Registry | Description |
|---|---|---|
| Docker image | quay.io/okdp/superset |
Apache Superset + Trino + PostgreSQL drivers + Authlib pre-installed. |
-dockerize variant |
quay.io/okdp/superset:<v>-dockerize |
Security-patched rebuild of apache/superset:<v>-dockerize (init utility). |
-websocket variant |
quay.io/okdp/superset:<v>-websocket |
Security-patched rebuild of apache/superset:<v>-websocket (websocket sidecar). |
| Helm chart | quay.io/okdp/charts/superset |
Wrapping chart with OKDP defaults. |
| Image | Tag examples |
|---|---|
quay.io/okdp/superset |
6.0.0, 6.0.0-1.0, 6.0.0-dockerize, 6.0.0-1.0-dockerize, 6.0.0-websocket, 6.0.0-1.0-websocket |
quay.io/okdp/charts/superset |
0.15.2-2.0, 0.15.2-1.0, 0.15.0-1.1 |
<superset-version>matches the upstream Apache Superset release (e.g.6.0.0).<superset-version>-<okdp-build>adds an OKDP-specific build number (e.g.6.0.0-1.0) — bumped whenever the OKDP layer changes without a Superset upgrade.- Chart versions follow
<chart-version>-<okdp-build>(e.g.0.15.2-2.0) where<chart-version>matches the upstream Apache Superset Helm chart.
This chart is consumed by the OKDP/okdp-sandbox environment via OKDP/platform-packages — wired to Keycloak (OAuth2/OIDC) for login and to Trino as a datasource.
helm installfails withCould not locate a version matching provided version string— OCI chart pulls do not resolve a default version; always pass--version <chart-version>tohelm install,helm upgradeandhelm pull.helm installfails withError: failed post-install: timed out waiting for the condition— the default Helm timeout (5 min) is too short on resource-constrained clusters (laptop, kind). The bundled PostgreSQL and Redis subcharts pin their image tag tolatest, which forcesimagePullPolicy: Alwaysand re-pulls these images at every install; the post-installinit-dbJob (which runs the OKDP Superset image and waits for PostgreSQL to be ready) cannot complete until those pulls finish. Pass--timeout 15m(or higher) to give the post-install hook enough time.- Pods stuck in
Pending— no defaultStorageClass, so PVCs cannot be bound. Either provision a defaultStorageClass, or disable persistence for testing:--set superset.postgresql.primary.persistence.enabled=false --set superset.redis.master.persistence.enabled=false. - After login, the browser loops back to
/login/— most often a mismatch betweenokdp.oauth.base_urland the IdP. Check thatbase_urldoes not end with/.well-known/openid-configuration(it is appended automatically), and that the IdP callback URL is set tohttps://<your-superset-host>/oauth-authorized/<provider>. - Web pod logs
ImportError: Authlib not installed— the deployment is not using the OKDP image. Setsuperset.image.repository=quay.io/okdp/supersetand a matchingsuperset.image.tag(or use the chart defaults).
Build and publication are automated via GitHub Actions (.github/workflows/):
ci.yml— on every PR and push: build the three Docker images (superset,-dockerize,-websocket), lint the Helm chart, regenerate helm-docs.release-please.yml— on merge tomain, release-please opens a release PR that bumps versions and updates theCHANGELOG. When merged, the Docker images are pushed toquay.io/okdp/supersetand the Helm chart toquay.io/okdp/charts/superset.docker-rebuild.yml— weekly rebuild of the latest release tag (Tuesday 05:00 UTC,cron: "0 5 * * 2") to pick up upstream base image security patches.helm-lint-template.yml— chart lint andhelm-docsregeneration.
Images are built and published for linux/amd64 and linux/arm64.
After running the Quick Start, check the Superset health endpoint:
kubectl port-forward svc/my-release-superset 8088:8088 &
curl -sL -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/healthExpected result:
200
For a deeper smoke test, run the Installation command with --values helm/superset/sample-values.yaml (which sets okdp.superset.load_examples.enabled=true) and confirm the example dashboards are loaded:
PG_PASS=$(kubectl get secret my-release-superset-db-env -o jsonpath='{.data.DB_PASS}' | base64 -d)
kubectl exec my-release-postgresql-0 -- \
env PGPASSWORD="$PG_PASS" psql -U superset -d superset -tAc \
"SELECT 'dashboards', count(*) FROM dashboards UNION ALL SELECT 'slices', count(*) FROM slices;"Expected result:
dashboards|11
slices|121
helm uninstall my-releaseThe PostgreSQL and Redis subcharts use StatefulSets with PVCs that are not deleted by helm uninstall. To fully wipe the metadata DB:
kubectl delete pvc -l app.kubernetes.io/instance=my-release- Apache Superset upstream Helm chart (
apache.github.io/superset) — bare chart without OAuth2 providers, Trino bundling, externalized secrets or multi-arch images. - Apache Superset on Docker Compose (
apache/supersetDocker Compose) — official non-Kubernetes deployment, mostly for local development. - Metabase — open-source BI tool, simpler to deploy but less extensible than Superset for SQL-heavy dashboards.
- Redash — open-source SQL dashboarding tool, smaller scope than Superset.
Contributions follow the OKDP contribution guide. Released under the Apache License 2.0.
Built 🚀 for the OKDP Community
