Skip to content

Apache Superset Kubernetes Operator

Alpha API

The API is still v1alpha1 — CRD schemas and behavior may change between releases until it stabilizes.

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 reconciles the Deployments, ConfigMaps, Services, lifecycle task Jobs, and supporting resources for that instance.

Features

  • Sensible defaults — defaults adjust based on the components and presets you configure
  • Automatic config rendering — structured fields for metastore, Valkey, Gunicorn, and Celery generate superset_config.py per component; config changes trigger rolling restarts
  • Configurable — defaults can be overridden at the preset, deployment-template, or container level, with a raw Python escape hatch in spec.config/spec.<component>.config for settings not surfaced as typed fields
  • Component toggle — enable CeleryWorker, CeleryBeat, CeleryFlower, McpServer, or WebsocketServer (experimental) by setting their spec; omit to disable
  • Maintenance-backed upgrades — when database migrations need to run, the operator drains components, runs the lifecycle tasks, and restores traffic only after the new version is healthy; an optional maintenance page can serve users during the window when configured
  • 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
  • Scaling and resilience — HPA with custom metrics, PodDisruptionBudgets, NetworkPolicies, Prometheus ServiceMonitor
  • Flexible install scope — cluster-scoped (default) or namespace-scoped; the namespace-scoped Helm install renders no manager ClusterRole. CRD installation and, unless metrics are disabled, secure metrics auth still require cluster-scoped RBAC — see installation for the exact constraints

Supported Kubernetes versions

  • Officially tested: Kubernetes 1.36, 1.35

Official support covers the two most recent Kubernetes minor versions with a published kind node image. The newest Kubernetes release gets best-effort coverage via a non-blocking CI lane until kind ships its node image.

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
  featureFlags:
    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.1.0"
  secretKeyFrom:
    name: superset-secret
    key: secret-key
  metastore:
    uriFrom:
      name: db-credentials
      key: connection-string
  featureFlags:
    ENABLE_TEMPLATE_PROCESSING: true
  webServer:
    replicas: 2
  mcpServer: {}

The operator resolves this into parent-owned resources. Lifecycle task Jobs run database migrations before components deploy, and their durable state is projected onto the parent status:

$ kubectl get supersets
NAME           VERSION   PHASE     READY   AVAILABLE   AGE
my-superset    latest    Running   3/3     True        5m

$ kubectl get superset my-superset -o jsonpath='{.status.lifecycle.migrate.state}'
Complete

$ 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, resource ownership, 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