Skip to content

Installation

This guide covers installing the operator and deploying a Superset instance in production. For a quick local trial, see Getting Started. For development setup, see Development Setup.

Prerequisites

  • Kubernetes v1.28+ cluster
  • Helm 3 (for Helm-based installation) or kubectl + kustomize
  • PostgreSQL or MySQL database
  • (Optional) Valkey (or Redis) — required when enabling caching, Celery task broker, or result backend
  • (Optional) Gateway API CRDs for HTTPRoute support — not included in Kubernetes, must be installed separately
  • (Optional) prometheus-operator CRDs for ServiceMonitor support

1. Install the operator

helm install superset-operator \
  oci://ghcr.io/apache/superset-kubernetes-operator/charts/superset-operator \
  --version <version> \
  --namespace superset-operator-system \
  --create-namespace

Replace <version> with a published chart version (e.g., 0.1.0). Use 0.0.0-dev for the latest build from main. When using the dev version, set image.pullPolicy=Always to ensure you always get the latest image:

helm install superset-operator \
  oci://ghcr.io/apache/superset-kubernetes-operator/charts/superset-operator \
  --version 0.0.0-dev \
  --namespace superset-operator-system \
  --create-namespace \
  --set image.pullPolicy=Always

See charts/superset-operator/values.yaml for all available Helm values and Downloads for published images and tag conventions.

2. Create secrets

Superset requires a secret key for session signing. In production, mount it as an environment variable:

kubectl create secret generic superset-secrets \
  --from-literal=secret-key="$(openssl rand -hex 32)"

If your database credentials should not appear in the CR, mount the full connection URI as a Secret too:

kubectl create secret generic superset-db \
  --from-literal=uri="postgresql+psycopg2://<user>:<password>@<host>:5432/<database>"

Replace the placeholders with your PostgreSQL connection details.

3. Deploy Superset

Create a Superset custom resource. In production (environment: Production, the default), CRD validation rejects inline secretKey, metastore.uri, metastore.password, and valkey.password. Reference secrets via secretKeyFrom, metastore.uriFrom, metastore.passwordFrom, or valkey.passwordFrom — the operator wires these as valueFrom.secretKeyRef env vars automatically:

kubectl apply -f - <<'EOF'
apiVersion: superset.apache.org/v1alpha1
kind: Superset
metadata:
  name: my-superset
spec:
  image:
    tag: "6.0.1"

  secretKeyFrom:
    name: superset-secrets
    key: secret-key

  metastore:
    uriFrom:
      name: superset-db
      key: uri

  webServer:
    replicas: 2
    service:
      type: ClusterIP
      port: 8088
EOF

The operator will create SupersetLifecycleTask child CRs to perform database migration and initialization, then create the web server child CR and its resources. Check task status with kubectl get supersetlifecycletasks.

4. Watch it come up

# Watch the parent CR status
kubectl get superset my-superset -w

# Watch init pods
kubectl get pods -l superset.apache.org/init-task -w

# Watch all pods
kubectl get pods -w

5. Access Superset

Port-forward to the web server service:

kubectl port-forward svc/my-superset-web-server 8088:8088

Open http://localhost:8088 in your browser.

Authentication

The operator does not manage Superset user accounts. Production deployments typically use an external authentication provider (OIDC, OAuth, LDAP) configured via spec.config. See the Superset security documentation for details.

6. Add Celery workers

Celery workers handle background tasks such as chart data caching, scheduled reports, and long-running queries. Add the Celery components and point them at your Valkey (or Redis) instance via spec.valkey:

kubectl apply -f - <<'EOF'
apiVersion: superset.apache.org/v1alpha1
kind: Superset
metadata:
  name: my-superset
spec:
  image:
    tag: "6.0.1"

  secretKeyFrom:
    name: superset-secrets
    key: secret-key

  metastore:
    uriFrom:
      name: superset-db
      key: uri

  valkey:
    host: valkey.default.svc

  webServer:
    replicas: 2
    service:
      type: ClusterIP
      port: 8088

  celeryWorker:
    replicas: 2

  celeryBeat: {}
EOF

The operator will create the CeleryWorker and CeleryBeat child CRs and their Deployments automatically.

Next steps