Kubernetes has become in 2026 the default deployment mode for Apache Superset in production: native high availability, horizontal scaling, rolling updates, managed secrets. The Apache Foundation maintains an official Helm chart that considerably simplifies installation. This article describes the target architecture, the step-by-step installation with Helm, configuration adjustments for production, and the pitfalls to avoid.
1. Why Kubernetes for Apache Superset
On Docker Compose, scaling Superset means manually adding containers, configuring a load balancer, managing persistent volumes by hand. On Kubernetes, the official Helm chart applies best practices directly: stateless Superset pods, separate Celery worker deployment, single beat scheduler, PVC for Postgres and Redis, ingress with automatic TLS via cert-manager.
If you want to avoid this complexity, TVL Managed Superset deploys a ready-to-use instance in less than 3 minutes, with the entire Kubernetes stack provisioned and maintained. But if you insist on self-hosting, Helm is the cleanest path.
2. Target architecture
The official apache/superset Helm chart typically deploys the following resources:
| Component | Kubernetes type | Recommended replicas |
|---|---|---|
| Superset web | Deployment + Service | 2-3 |
| Superset worker (Celery) | Deployment | 2 |
| Superset worker beat | Deployment | 1 (singleton) |
| Superset init job | Job (one-shot) | — |
| PostgreSQL (sub-chart) | StatefulSet + PVC | 1 (or external) |
| Redis (sub-chart) | StatefulSet + PVC | 1 (or external) |
| Ingress | Ingress + cert-manager | — |
3. Prerequisites
- A Kubernetes 1.28+ cluster (tested on 1.34 at OVH Managed Kubernetes).
kubectl1.28+ andhelm3.13+ (Helm 4 works but renamed some flags).- An available StorageClass (OVH case:
csi-cinder-high-speed). - An installed ingress controller (
ingress-nginxpreferred). cert-managerwith a Let's Encrypt ClusterIssuer if you want automatic TLS.- A domain pointing to the ingress IP.
4. Add the Helm repo
helm repo add superset https://apache.github.io/superset
helm repo update
helm search repo superset/superset --versions | head -10
At time of writing, the stable chart version is 0.15.2 bundling Superset application 5.0.0. Always pin the version explicitly.
5. Minimal installation
For a quick start in a dedicated namespace:
kubectl create namespace superset
helm install superset superset/superset \
--namespace superset \
--version 0.15.2 \
--set redis.enabled=true \
--set postgresql.enabled=true \
--timeout 10mCheck that all pods are Running:
kubectl get pods -n superset
# superset-postgresql-0 1/1 Running
# superset-redis-master-0 1/1 Running
# superset-init-db-... 0/1 Completed
# superset-849f... 1/1 Running
# superset-worker-... 1/1 Running
# superset-worker-beat-... 1/1 RunningUI accessible via port-forward while you configure ingress:
kubectl port-forward -n superset svc/superset 8088:80886. Custom values.yaml
In production, never launch with default values. Here's a minimal but sane values.yaml:
image:
repository: apache/superset
tag: "5.0.0"
# External domain
ingress:
enabled: true
ingressClassName: nginx
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
hosts:
- bi.example.com
tls:
- secretName: superset-tls
hosts:
- bi.example.com
# Replicas
supersetNode:
replicaCount: 2
resources:
requests: { cpu: 250m, memory: 1Gi }
limits: { cpu: 1000m, memory: 2Gi }
supersetWorker:
replicaCount: 2
resources:
requests: { cpu: 250m, memory: 1Gi }
# Secrets injected via pre-created K8s secret
supersetSecretsExtra:
- existingSecret: superset-secrets
keys: [SUPERSET_SECRET_KEY]
# Bootstrap: connector and driver additions
bootstrapScript: |
#!/bin/bash
set -eu
uv pip install psycopg2-binary clickhouse-connect snowflake-sqlalchemy authlib
# External DB and Redis (recommended in prod)
postgresql:
enabled: false
redis:
enabled: false
supersetNode:
connections:
db_host: "postgres.example.com"
db_port: 5432
db_user: superset
db_pass: "${POSTGRES_PASSWORD}"
db_name: superset
redis_host: "redis.example.com"
redis_port: 63797. The psycopg driver trap
The apache/superset:5.0.0 image embeds Python 3.10 in a uv venv, without psycopg2 by default. If you use Postgres as metadata DB (typical case), add the driver via bootstrapScript with uv pip install and not pip install — otherwise the module installs outside the venv and isn't found by Superset.
bootstrapScript: |
#!/bin/bash
set -eu
uv pip install psycopg2-binary authlib
Also, SQLAlchemy 1.4 in this image only knows the psycopg2 dialect (not psycopg v3). The URI must remain postgresql+psycopg2://..., which is the chart's default.
8. Bitnami → bitnamilegacy
Since August 2025, Bitnami removed most of its images from the public docker.io/bitnami/* registry. The Superset chart 0.15.2 still references the old repo for Postgres and Redis sub-charts. If you enable these sub-charts in cluster, override the image to docker.io/bitnamilegacy/*:
postgresql:
image:
registry: docker.io
repository: bitnamilegacy/postgresql
tag: 14.17.0-debian-12-r3
redis:
image:
registry: docker.io
repository: bitnamilegacy/redis
tag: 7.0.10-debian-11-r4Otherwise you get ImagePullBackOffs that aren't immediately explicit.
9. Secret management
Never commit Superset's SECRET_KEY, Postgres credentials, or API keys in values.yaml. Use a pre-created Kubernetes Secret:
kubectl create secret generic superset-secrets \
-n superset \
--from-literal=SUPERSET_SECRET_KEY="$(openssl rand -base64 42)" \
--from-literal=POSTGRES_PASSWORD="$(openssl rand -base64 24)"To go further, integrate External Secrets Operator with an external vault (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault).
10. Ingress, TLS and cert-manager
For automatic TLS with Let's Encrypt, create a ClusterIssuer:
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: ops@example.com
privateKeySecretRef:
name: letsencrypt-prod
solvers:
- http01:
ingress:
class: nginx
Once in place, the annotation cert-manager.io/cluster-issuer: letsencrypt-prod on the Ingress is enough to provision the certificate automatically. This configuration is automatically managed by TVL Managed Superset.
11. Horizontal scaling
The Superset web pod is stateless (sessions in Redis), so horizontal scaling is painless. To automate:
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: superset-web
namespace: superset
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: superset
minReplicas: 2
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target: { type: Utilization, averageUtilization: 70 }Same for the Celery worker. The beat (scheduler), however, remains a singleton. See our article on Superset HA architecture.
12. Rolling updates
Helm handles rolling updates automatically. To upgrade:
helm upgrade superset superset/superset \
-n superset \
-f values.yaml \
--version 0.16.0 \
--timeout 10mThe superset-init job applies Alembic migrations. Always backup Postgres before upgrading and test in staging first.
13. Monitoring and logs
Superset exposes Prometheus metrics since 4.x via a /metrics endpoint enabled by the STATSD feature flag. For log centralization, two approaches:
- Loki + Promtail: pod log retrieval, Grafana-style querying.
- ELK / OpenSearch: full-text indexing, heavier but feature-rich.
Don't forget: also centralize Superset audit logs (who saw which dashboard, who ran which query). See our article on Superset monitoring with Prometheus + Grafana.
14. Backups
On Kubernetes, two backup levels:
- The Superset metadata PostgreSQL DB: daily pg_dump, stored off-cluster (S3, OVH Cold Archive).
- Persistent volumes (PVC): VolumeSnapshot snapshots via Velero or cloud-specific operator.
The simplest in practice is to use a managed external PostgreSQL (OVH Public Cloud Database, AWS RDS, Azure Database) with built-in backups.
15. Common troubleshooting
"psycopg2 module not found"
See section 7 — use uv pip install in bootstrap, not pip install.
Helm release stuck in pending-install
If helm install is interrupted (Ctrl+C, crash), a zombie release persists. To recover: helm uninstall <release> -n <ns> --no-hooks then clean up residual resources with kubectl delete pvc --all -n <ns> if you accept losing data.
PVCs survive helm uninstall
Expected behavior: don't lose data by accident. For a complete wipe: kubectl delete pvc --all -n <ns> after helm uninstall.
Init job fails with timeout
Either the Postgres DB isn't reachable (check credentials and network), or the Alembic migration takes more than 5 minutes (very large existing DB). Increase initJob.activeDeadlineSeconds.
FAQ — Apache Superset Kubernetes
Do you need a dedicated Kubernetes cluster for Superset?
No, Superset cohabits very well with other apps in the same cluster. A dedicated namespace and ResourceQuota/LimitRange suffice for isolation.
What cluster size for 100 users?
Plan 2 vCPU and 4 GB RAM for the Superset application stack (web + worker + beat), plus the database. For 100 users with moderate use, 3 nodes of 4 vCPU/8 GB usually suffice.
Is the Helm chart production-ready?
Yes, it's the chart maintained by the Apache Foundation and used by many companies in production. Some configuration adjustments (cf. this article) remain necessary to move from demo to prod.
Can ArgoCD or Flux be used for GitOps?
Yes without difficulty. The values.yaml is the committed source of truth, ArgoCD applies. Ensure Secrets aren't in the Git repo (use SealedSecrets or ESO).
Conclusion
Kubernetes brings to Apache Superset the operational robustness expected in production: high availability, scaling, rolling updates, managed secrets. The official Helm chart avoids most of the work, but requires some adjustments (psycopg driver, bitnamilegacy image, ingress TLS) that consume several days of fine-tuning the first time.
Want the benefits of Apache Superset without the friction of installation and maintenance? Deploy your instance in 3 clicks with TVL Managed Superset, hosted in Europe (OVHcloud, Roubaix, France), on a managed Kubernetes cluster. For more, see our articles on Docker installation and the Apache Superset production checklist.