Development Setup

This guide walks through setting up a local development environment with Kind, PostgreSQL, and Valkey. By the end you will have a working Superset instance running on your laptop.

Prerequisites

Tool	Version	Install
Docker daemon	20+	Docker Desktop, Colima (`brew install colima`), or Podman
kubectl	1.27+	kubernetes.io
Kind	0.30+	`brew install kind` or `go install sigs.k8s.io/kind@latest`
Go	1.26+	`brew install go` or go.dev

macOS notes

Colima is a lightweight alternative to Docker Desktop. Start it with enough headroom for Kind plus a Superset deployment:
```
colima start --cpu 4 --memory 8 --disk 50
```
The Docker CLI auto-switches to the colima context.
If you previously ran Docker Desktop and have switched to Colima, the leftover credsStore: desktop in ~/.docker/config.json will fail every docker pull with a keychain error in non-interactive shells. Remove the credsStore and plugins/features.hooks keys from that file (they only apply to Docker Desktop).

1. Create a Kind cluster

kind create cluster --name superset

2. Deploy PostgreSQL

kubectl create deployment postgres --image=postgres:16 \
  --port=5432 \
  -- sh -c 'exec postgres'
kubectl set env deployment/postgres \
  POSTGRES_USER=superset \
  POSTGRES_PASSWORD=superset \
  POSTGRES_DB=superset
kubectl expose deployment postgres --port=5432

Wait for the pod to be ready:

kubectl wait --for=condition=available deployment/postgres --timeout=60s

3. Deploy Valkey

kubectl create deployment valkey --image=valkey/valkey:8 --port=6379
kubectl expose deployment valkey --port=6379

4. Run the operator

There are two ways to run the operator:

Option A: Run locally (outside the cluster)

make run

This compiles and runs the operator process on your machine, connecting to the Kind cluster via your kubeconfig. Leave this terminal open — it streams reconciliation logs.

Option B: Deploy in-cluster

make docker-build IMG=superset-operator:dev
kind load docker-image superset-operator:dev --name superset
make deploy IMG=superset-operator:dev

This builds the operator image, loads it into Kind, and deploys it as a Deployment with all RBAC and CRDs. View logs with:

kubectl logs -n superset-operator-system deployment/superset-operator-controller-manager -f

make deploy is a superset of make install — it installs CRDs, RBAC, and the operator Deployment in one step.

5. Deploy Superset

kubectl apply -f config/samples/superset_v1alpha1_superset.yaml

The sample manifest deploys a web server in dev mode, runs the init task, and points at the Postgres instance created above.

6. Access Superset

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

Open http://localhost:8088.

7. Clean up

kubectl delete superset superset-sample
kind delete cluster --name superset

Make Commands

License

Command	Description
`make check-license`	Check Apache license headers using Apache Rat.

Documentation

Command	Description
`make docs-lock`	Regenerate hash-pinned Python dependencies for documentation.
`make docs-serve`	Serve documentation locally with live reload.
`make docs-build`	Build documentation site.
`make docs-api`	Generate API reference documentation from Go types.
`make supported-versions`	Regenerate the supported-Kubernetes-versions table in README.md and docs.
`make make-commands`	Regenerate the make-commands tables in the contributing docs.
`make sync-supported-versions`	Sync .github/supported-k8s.json with the pinned kind release's node images.
`make verify-supported-versions`	Verify supported-k8s.json matches the pinned kind release and docs are up to date.

Helm

Command	Description
`make helm-sync-crds`	Sync generated CRDs into the Helm chart.
`make helm`	Sync CRDs into Helm chart and package it. The chart `appVersion` is derived from VERSION at package time.
`make helm-lint`	Lint the Helm chart (syncs CRDs first).

Development

Command	Description
`make codegen`	Regenerate all generated artifacts (CRDs, DeepCopy, Helm CRDs, API docs, supported-versions table, make-commands tables).
`make clean`	Remove build artifacts, downloaded tools, and test cache.
`make manifests`	Generate ClusterRole and CustomResourceDefinition objects.
`make generate`	Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
`make fmt`	Run go fmt against code.
`make vet`	Run go vet against code.
`make test`	Run all tests (unit + integration + e2e).
`make test-unit`	Run unit tests (no envtest or cluster required).
`make test-integration`	Run integration tests (requires envtest).
`make fuzz`	Run all fuzz targets for a bounded duration (FUZZTIME per target, default 30s).
`make setup-test-e2e`	Set up a Kind cluster for e2e tests if it does not exist
`make test-e2e`	Run the e2e tests. Expected an isolated environment using Kind.
`make cleanup-test-e2e`	Tear down the Kind cluster used for e2e tests
`make lint`	Run golangci-lint linter
`make lint-fix`	Run golangci-lint linter and perform fixes
`make lint-config`	Verify golangci-lint linter configuration
`make hooks`	Configure git to use .githooks/ for pre-commit hooks

Build

Command	Description
`make build`	Build manager binary.
`make run`	Run a controller from your host. Pass flags via ARGS, e.g. make run ARGS=“--zap-log-level=2”.
`make docker-build`	Build docker image with the manager.
`make docker-push`	Push docker image with the manager.
`make build-installer`	Generate a consolidated YAML with CRDs and deployment.

Deployment

Command	Description
`make install`	Install CRDs into the K8s cluster specified in ~/.kube/config.
`make uninstall`	Uninstall CRDs from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
`make deploy`	Deploy controller to the K8s cluster specified in ~/.kube/config.
`make undeploy`	Undeploy controller from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.

Pre-Commit Hooks

The project includes a lightweight git hook at .githooks/pre-commit that runs make lint before each commit. No external tools required — it uses golangci-lint, which covers formatting (gofmt, goimports), go vet, and all configured linters.

Setup

make hooks

This sets core.hooksPath to .githooks/ for this repository. To bypass the hook for a specific commit, use git commit --no-verify.

Documentation

The docs are built with mkdocs-material. To set up and preview locally:

virtualenv venv
source venv/bin/activate
python -m pip install --require-hashes -r docs-requirements.txt
make docs-serve

This starts a live-reloading server at http://localhost:8000. Edit Markdown files in docs/ and changes appear instantly.

The documentation dependency lock is generated from docs-requirements.in. After changing documentation dependencies, run make docs-lock and commit the updated docs-requirements.txt.

To verify the docs build cleanly (same check that runs in CI):

make docs-build

Diagrams

Use Mermaid for flow diagrams. Keep them compact with the following conventions:

Use flowchart TD (top-down) for state machines and lifecycle flows
Set font size to 12px via init config: %%{init: {'theme': 'neutral', 'themeVariables': {'fontSize': '12px'}}}%%
Use short node labels (abbreviate where clear from context)
Prefer single-letter node IDs (A, B, C) for readability of the source

API Reference

The API reference is generated from Go type definitions using crd-ref-docs. After modifying types in api/v1alpha1/, run make codegen to regenerate all generated artifacts (CRDs, DeepCopy, Helm CRDs, API docs). CI verifies nothing is stale.

The API reference only documents operator-defined types. Built-in Kubernetes types (e.g., Affinity, Container, Volume) are linked out to pkg.go.dev rather than rendered inline. When adding new fields that reference a K8s type, add a corresponding knownTypes entry in hack/api-ref-config.yaml so it renders as a link.