You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by vi...@apache.org on 2026/05/29 16:47:44 UTC
(superset-kubernetes-operator) branch main updated: docs: refresh README and soften pre-release banners (#98)
This is an automated email from the ASF dual-hosted git repository.
villebro pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/superset-kubernetes-operator.git
The following commit(s) were added to refs/heads/main by this push:
new efb255c docs: refresh README and soften pre-release banners (#98)
efb255c is described below
commit efb255c23d8de90b7898ce82825dd6d2ebfe3850
Author: Ville Brofeldt <33...@users.noreply.github.com>
AuthorDate: Fri May 29 09:47:38 2026 -0700
docs: refresh README and soften pre-release banners (#98)
* docs: security-audit alignment and README refresh
* clarify frameworks
---
AGENTS.md | 2 +-
Makefile | 2 +-
README.md | 119 ++++++++++--------------------
docs/contributing/development-setup.md | 2 +-
docs/index.md | 4 +-
internal/controller/lifecycle_job.go | 7 +-
internal/controller/lifecycle_job_test.go | 6 +-
scripts/render-make-commands.sh | 5 +-
8 files changed, 57 insertions(+), 90 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 23cac58..7b33d2a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,7 +17,7 @@ specific language governing permissions and limitations
under the License.
-->
-# CLAUDE.md
+# LLM Context Guide for Apache Superset Kubernetes Operator
## Project Overview
diff --git a/Makefile b/Makefile
index ba7a8fb..e132ffb 100644
--- a/Makefile
+++ b/Makefile
@@ -133,7 +133,7 @@ supported-versions: ## Regenerate the supported-Kubernetes-versions table in REA
./scripts/render-supported-versions.sh
.PHONY: make-commands
-make-commands: ## Regenerate the make-commands tables in README.md and the contributing docs.
+make-commands: ## Regenerate the make-commands tables in the contributing docs.
./scripts/render-make-commands.sh
.PHONY: sync-supported-versions
diff --git a/README.md b/README.md
index 40eb418..462a1bb 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ under the License.
# Apache Superset Kubernetes Operator
-> **Warning**: 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.
+> **Note**: The API is still `v1alpha1` — CRD schemas and behavior may change between releases until it stabilizes.
[](https://github.com/apache/superset-kubernetes-operator/actions/workflows/ci.yaml)
[](https://codecov.io/gh/apache/superset-kubernetes-operator)
@@ -27,9 +27,24 @@ under the License.
[](https://opensource.org/licenses/Apache-2.0)
[](https://apache.github.io/superset-kubernetes-operator/)
-A Kubernetes operator for deploying and managing [Apache Superset](https://superset.apache.org/) on Kubernetes. Read the [documentation](https://apache.github.io/superset-kubernetes-operator/) to get started. Built with the Go-based [Operator SDK](https://sdk.operatorframework.io/).
+**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.
-The operator manages the full Superset lifecycle: database migrations, configuration rendering, component deployment, scaling, and networking. Defaults are tuned for typical deployments; presets, deployment-template fields, and a raw Python escape hatch let you override them where needed.
+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 needs no cluster-wide RBAC at all.
+
+→ See the [full feature overview](https://apache.github.io/superset-kubernetes-operator/) in the docs.
## Supported Kubernetes versions
@@ -69,84 +84,32 @@ spec:
environment: Development
secretKey: thisIsNotSecure_changeInProduction!
metastore:
- uri: postgresql+psycopg2://superset:superset@postgres:5432/superset
+ 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.uriFrom` 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.
-
-## Development
-
-<!-- BEGIN MAKE-COMMANDS -->
-<!-- generated by `make codegen`; do not edit -->
-### License
-
-| Command | Description |
-|---|---|
-| `make check-license` | Check Apache license headers using Apache Rat. |
-
-### Documentation
-
-| Command | Description |
-|---|---|
-| `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 README.md and 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 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. |
-| `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. |
-<!-- END MAKE-COMMANDS -->
-
-After editing type definitions in `api/v1alpha1/`, run `make codegen` and commit the generated files alongside your changes.
+> **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.
## License
diff --git a/docs/contributing/development-setup.md b/docs/contributing/development-setup.md
index 0416090..24616f3 100644
--- a/docs/contributing/development-setup.md
+++ b/docs/contributing/development-setup.md
@@ -145,7 +145,7 @@ kind delete cluster --name superset
| `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 README.md and the contributing 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. |
diff --git a/docs/index.md b/docs/index.md
index 2fae173..b63d37c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -19,8 +19,8 @@ under the License.
# Apache Superset Kubernetes Operator
-!!! warning "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.
+!!! note "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](https://superset.apache.org/). Built with the Go-based [Operator SDK](https://sdk.operatorframework.io/).
diff --git a/internal/controller/lifecycle_job.go b/internal/controller/lifecycle_job.go
index bf1daab..9325f3d 100644
--- a/internal/controller/lifecycle_job.go
+++ b/internal/controller/lifecycle_job.go
@@ -454,9 +454,14 @@ func jobFailureMessage(job *batchv1.Job) string {
return "Job failed"
}
+// truncationMarker is appended to a failure message when it is truncated. It is
+// counted against maxTerminationMessageLen so the returned string never exceeds
+// that budget.
+const truncationMarker = "..."
+
func truncateFailureMessage(msg string) string {
if len(msg) > maxTerminationMessageLen {
- return msg[:maxTerminationMessageLen] + "..."
+ return msg[:maxTerminationMessageLen-len(truncationMarker)] + truncationMarker
}
return msg
}
diff --git a/internal/controller/lifecycle_job_test.go b/internal/controller/lifecycle_job_test.go
index db2f1bd..d3f831d 100644
--- a/internal/controller/lifecycle_job_test.go
+++ b/internal/controller/lifecycle_job_test.go
@@ -352,8 +352,8 @@ func TestTruncateFailureMessage(t *testing.T) {
t.Run("over-limit message is truncated with ellipsis", func(t *testing.T) {
msg := strings.Repeat("x", maxTerminationMessageLen+10)
got := truncateFailureMessage(msg)
- assert.Equal(t, strings.Repeat("x", maxTerminationMessageLen)+"...", got)
- assert.Len(t, got, maxTerminationMessageLen+3)
+ assert.Equal(t, strings.Repeat("x", maxTerminationMessageLen-len(truncationMarker))+"...", got)
+ assert.Len(t, got, maxTerminationMessageLen)
})
}
@@ -386,6 +386,6 @@ func TestJobFailureMessage(t *testing.T) {
t.Run("truncates long condition messages", func(t *testing.T) {
long := strings.Repeat("x", maxTerminationMessageLen+5)
got := jobFailureMessage(failed("BackoffLimitExceeded", long))
- assert.Len(t, got, maxTerminationMessageLen+3)
+ assert.Len(t, got, maxTerminationMessageLen)
})
}
diff --git a/scripts/render-make-commands.sh b/scripts/render-make-commands.sh
index a13d36c..ac005d7 100755
--- a/scripts/render-make-commands.sh
+++ b/scripts/render-make-commands.sh
@@ -15,8 +15,8 @@
# limitations under the License.
#
# Render the make-commands tables from the Makefile's `##@ Section` headers
-# and `target: ## description` annotations into README.md and the contributing
-# docs, between sentinel comments:
+# and `target: ## description` annotations into the contributing docs, between
+# sentinel comments:
#
# <!-- BEGIN MAKE-COMMANDS -->
# ... generated block ...
@@ -31,7 +31,6 @@ set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
MAKEFILE="${REPO_ROOT}/Makefile"
TARGETS=(
- "${REPO_ROOT}/README.md"
"${REPO_ROOT}/docs/contributing/development-setup.md"
)
SKIP_SECTIONS_RE='^(General|Dependencies)$'