Skip to content

Apache Superset Kubernetes Operator

Under Development

This project is under active development and is not yet stable. APIs, CRD schemas, and behavior may change without notice between releases. Do not use in production.

A Kubernetes operator for deploying and managing Apache Superset. Built with the Go-based Operator SDK.

The operator manages the full Superset lifecycle: database migrations, configuration rendering, component deployment, scaling, and networking. Users define a single Superset custom resource, and the operator resolves it into per-component child CRDs that each manage their own Deployment, ConfigMap, and Service.

Features

  • Sane defaults — production-ready settings out of the box that adapt automatically to your workload
  • Automatic config rendering — structured fields for metastore, Valkey, Gunicorn, and Celery generate correct superset_config.py per component; config changes trigger rolling restarts
  • Full control — every default is overridable, from high-level presets down to individual container fields, with a raw Python escape hatch for anything not covered
  • Component toggle — enable CeleryWorker, CeleryBeat, CeleryFlower, WebsocketServer, or McpServer by setting their spec; omit to disable
  • Zero-downtime upgrades — maintenance page serves users during database migrations; the operator drains components gracefully, runs lifecycle tasks, and restores traffic only after the new version is healthy
  • Lifecycle automation — database cloning, schema migrations, secret key rotation, and application init run as sequenced tasks with automatic change detection and checksum-based re-execution
  • Networking — Gateway API (HTTPRoute) and Ingress support with per-component routing
  • Production hardening — HPA with custom metrics, PodDisruptionBudgets, NetworkPolicies, Prometheus ServiceMonitor

What it looks like

A typical Superset deployment for getting started in dev mode:

apiVersion: superset.apache.org/v1alpha1
kind: Superset
metadata:
  name: my-superset
spec:
  image:
    tag: "latest"
  environment: Development
  secretKey: thisIsNotSecure_changeInProduction!
  metastore:
    host: postgres
    port: 5432
    database: superset
    username: superset
    password: superset
  config: |
    FEATURE_FLAGS = {"ENABLE_TEMPLATE_PROCESSING": True}
  webServer:
    replicas: 2
  mcpServer: {}
  lifecycle:
    init:
      adminUser: {}
      loadExamples: true

For production, use secretKeyFrom and metastore.uriFrom to reference Kubernetes Secrets instead of inline values:

apiVersion: superset.apache.org/v1alpha1
kind: Superset
metadata:
  name: my-superset
spec:
  image:
    tag: "6.0.1"
  secretKeyFrom:
    name: superset-secret
    key: secret-key
  metastore:
    uriFrom:
      name: db-credentials
      key: connection-string
  config: |
    FEATURE_FLAGS = {"ENABLE_TEMPLATE_PROCESSING": True}
  webServer:
    replicas: 2
  mcpServer: {}

The operator resolves this into child CRDs and their underlying resources. The init child CR runs database migrations before components deploy:

$ kubectl get supersets
NAME           PHASE     VERSION   AGE
my-superset    Running   latest     5m

$ kubectl get supersetlifecycletasks
NAME                     PHASE      ATTEMPTS   AGE
my-superset-migrate      Complete   1          5m
my-superset-init         Complete   1          5m

$ kubectl get pods -l app.kubernetes.io/name=superset
NAME                                          READY   STATUS    AGE
my-superset-web-server-6d4b8c7f9-k2x8m        1/1     Running   4m
my-superset-web-server-6d4b8c7f9-p9f3n        1/1     Running   4m
my-superset-mcp-server-5c6d7e8f9-x9y1z        1/1     Running   4m

Where to start

Deploying Superset?

Configuring an existing deployment?

Understanding how the operator works?

  • Architecture — CRD hierarchy, config rendering pipeline
  • Internals — reconciliation phases, child controllers, status

Contributing code?

Reference:

  • API Reference — auto-generated CRD type documentation
  • Security — trust boundaries, threat model, vulnerability reporting
  • Downloads — images, Helm chart, verification

License

Apache License 2.0