<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
# Apache Superset Kubernetes Operator
> **Note**: The API is still `v1alpha1` — CRD schemas and behavior may change between releases until it stabilizes.
[](https://www.bestpractices.dev/projects/13114) [](https://scorecard.dev/viewer/?uri=github.com/apache/superset-kubernetes-operator) [](https://github.com/apache/superset-kubernetes-operator/actions/workflows/ci.yaml) [](https://codecov.io/gh/apache/superset-kubernetes-operator) [](https://opensource.org/licenses/Apache-2.0) [](https://apache.github.io/superset-kubernetes-operator/)
**Run Apache Superset on Kubernetes from a single custom resource.** Define one `Superset` object and the operator reconciles everything that stands behind a working Superset — Deployments, Services, ConfigMaps, lifecycle Jobs, and the supporting resources — keeping migrations, configuration, scaling, and networking in sync as your spec changes.
Read the [documentation](https://apache.github.io/superset-kubernetes-operator/) to get started, or jump straight to the [quick start](#quick-start).
## Highlights
- **One resource, full lifecycle** — a single `Superset` CR drives database migrations, secret-key rotation, config rendering, and component rollout.
- **Safe upgrades** — components drain, lifecycle tasks run, and traffic returns only once the new version is healthy, with an optional maintenance page for the window.
- **Batteries included, never locked in** — tuned defaults and presets for Gunicorn, Celery, the metastore, and Valkey, with a raw Python escape hatch for anything not surfaced as a typed field.
- **Production operations built in** — autoscaling, PodDisruptionBudgets, NetworkPolicies, Gateway API / Ingress routing, and a Prometheus ServiceMonitor.
- **Fits your cluster** — cluster-scoped or namespace-scoped installs; the namespace-scoped Helm install renders no manager `ClusterRole` (CRD installation and, unless disabled, secure metrics auth still need cluster-scoped RBAC — see [installation](https://apache.github.io/superset-kubernetes-operator/user-guide/installation/#namespace-scoped-install)).
→ See the [full feature overview](https://apache.github.io/superset-kubernetes-operator/) in the docs.
## Supported Kubernetes versions
<!-- BEGIN SUPPORTED-K8S -->
<!-- generated by `make supported-versions`; do not edit -->
- **Officially tested:** Kubernetes 1.37, 1.36, 1.35
<!-- END SUPPORTED-K8S -->
Official support covers the three most recent Kubernetes minor versions with a published [kind](https://kind.sigs.k8s.io/) node image.
Older releases are likely to work but are not tested. The practical minimum is **Kubernetes 1.25**: the operator's CRD validation is implemented entirely with
[CEL validation rules](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules),
which are enabled by default as beta from 1.25 and graduated to GA in 1.29. On clusters older than 1.25 the CRD still installs, but these rules are silently ignored — meaning the operator's secret-handling and configuration-safety checks are not enforced. Horizontal Pod Autoscaling additionally requires the `autoscaling/v2` API (Kubernetes 1.23+).
## Quick Start
Install the operator via Helm:
```sh
helm install superset-operator \
oci://ghcr.io/apache/superset-kubernetes-operator/charts/superset-operator \
--version <version> \
--namespace superset-operator-system \
--create-namespace
```
Then create a minimal Superset instance:
```yaml
apiVersion: superset.apache.org/v1alpha1
kind: Superset
metadata:
name: my-superset
spec:
image:
tag: "6.1.0"
environment: Development
secretKey: thisIsNotSecure_changeInProduction!
metastore:
host: postgres
port: 5432
database: superset
username: superset
password: superset
webServer: {}
```
> **Note**: The example above uses `environment: Development` for simplicity. In production (the default), use `secretKeyFrom` and `metastore.passwordFrom` to reference Kubernetes Secrets. See the [User Guide](https://apache.github.io/superset-kubernetes-operator/user-guide/configuration/) and the [sample manifests](config/samples/) for production examples.
## Under the hood
For the plumbing-curious:
- **Language & framework** — written in Go, scaffolded with the [Operator SDK](https://sdk.operatorframework.io/) and built on [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime). Validation is CEL-based on the CRD — no admission webhooks to operate.
- **Kubernetes APIs** — tracks the current `k8s.io` client libraries and [Gateway API](https://gateway-api.sigs.k8s.io/); exact pinned versions live in [`go.mod`](go.mod).
- **Image & supply chain** — distroless, multi-architecture (amd64/arm64) container; releases are [Cosign](https://github.com/sigstore/cosign)-signed; dependencies are kept current via [Renovate](https://docs.renovatebot.com/) with a minimum release age.
- **Design & internals** — a single public CRD reconciled into parent-owned resources. See the [architecture overview](https://apache.github.io/superset-kubernetes-operator/architecture/overview/) and the [security & supply-chain notes](https://apache.github.io/superset-kubernetes-operator/reference/security/).
## Contributing
Contributions are welcome. Development setup, the full list of `make` commands, the testing philosophy, and the code-generation workflow live in the [contributing guide](docs/contributing/development-setup.md). After editing type definitions in `api/v1alpha1/`, run `make codegen` and commit the generated files alongside your changes.
Using the operator? Add your organization to [ADOPTERS.md](ADOPTERS.md).
## License
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.