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/09 17:08:09 UTC
(superset-kubernetes-operator) branch main updated: docs: document status phases, supervised upgrades, and lifecycle config (#36)
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 9fdc474 docs: document status phases, supervised upgrades, and lifecycle config (#36)
9fdc474 is described below
commit 9fdc47414509fa39188ee10aeae3ffab969bde9b
Author: Ville Brofeldt <33...@users.noreply.github.com>
AuthorDate: Sat May 9 10:08:05 2026 -0700
docs: document status phases, supervised upgrades, and lifecycle config (#36)
---
api/v1alpha1/superset_types.go | 2 +-
.../crds/superset.apache.org_supersets.yaml | 1 +
.../crd/bases/superset.apache.org_supersets.yaml | 1 +
docs/api-reference.md | 2 +-
docs/internals.md | 37 +++++++-
docs/user-guide.md | 105 +++++++++++++++++++--
6 files changed, 136 insertions(+), 12 deletions(-)
diff --git a/api/v1alpha1/superset_types.go b/api/v1alpha1/superset_types.go
index ec31266..29df45d 100644
--- a/api/v1alpha1/superset_types.go
+++ b/api/v1alpha1/superset_types.go
@@ -522,7 +522,7 @@ type SupersetStatus struct {
ConfigChecksum string `json:"configChecksum,omitempty"`
// High-level phase.
// +optional
- // +kubebuilder:validation:Enum=Initializing;Upgrading;Running;Degraded;Suspended;Blocked;AwaitingApproval
+ // +kubebuilder:validation:Enum=Initializing;Upgrading;Draining;Running;Degraded;Suspended;Blocked;AwaitingApproval
Phase string `json:"phase,omitempty"`
}
diff --git a/charts/superset-operator/crds/superset.apache.org_supersets.yaml b/charts/superset-operator/crds/superset.apache.org_supersets.yaml
index f034a06..2d2a01f 100644
--- a/charts/superset-operator/crds/superset.apache.org_supersets.yaml
+++ b/charts/superset-operator/crds/superset.apache.org_supersets.yaml
@@ -31996,6 +31996,7 @@ spec:
enum:
- Initializing
- Upgrading
+ - Draining
- Running
- Degraded
- Suspended
diff --git a/config/crd/bases/superset.apache.org_supersets.yaml b/config/crd/bases/superset.apache.org_supersets.yaml
index f034a06..2d2a01f 100644
--- a/config/crd/bases/superset.apache.org_supersets.yaml
+++ b/config/crd/bases/superset.apache.org_supersets.yaml
@@ -31996,6 +31996,7 @@ spec:
enum:
- Initializing
- Upgrading
+ - Draining
- Running
- Degraded
- Suspended
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 766c899..e0ef151 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1300,7 +1300,7 @@ _Appears in:_
| `lastLifecycleImage` _string_ | Last image (repository:tag) that successfully completed the lifecycle.<br />Used to detect image changes on subsequent reconciles. | | Optional: \{\} <br /> |
| `version` _string_ | | | Optional: \{\} <br /> |
| `configChecksum` _string_ | | | Optional: \{\} <br /> |
-| `phase` _string_ | High-level phase. | | Enum: [Initializing Upgrading Running Degraded Suspended Blocked AwaitingApproval] <br />Optional: \{\} <br /> |
+| `phase` _string_ | High-level phase. | | Enum: [Initializing Upgrading Draining Running Degraded Suspended Blocked AwaitingApproval] <br />Optional: \{\} <br /> |
#### SupersetWebServer
diff --git a/docs/internals.md b/docs/internals.md
index 6ca1694..15276d8 100644
--- a/docs/internals.md
+++ b/docs/internals.md
@@ -200,8 +200,10 @@ Task pods transition through these states:
| Setting | Default | Description |
|---|---|---|
-| `spec.lifecycle.maxRetries` | `3` | Maximum attempts before permanent failure |
-| `spec.lifecycle.timeout` | `300s` | Maximum time per attempt |
+| `spec.lifecycle.migrate.maxRetries` | `3` | Maximum attempts before permanent failure |
+| `spec.lifecycle.migrate.timeout` | `5m` | Maximum time per attempt |
+| `spec.lifecycle.init.maxRetries` | `3` | Maximum attempts before permanent failure |
+| `spec.lifecycle.init.timeout` | `5m` | Maximum time per attempt |
**Backoff calculation:**
@@ -512,7 +514,7 @@ The parent `Superset` CR reports aggregate status:
```yaml
status:
- phase: Running # Initializing | Running | Degraded | Suspended
+ phase: Running
observedGeneration: 3
version: "latest"
components:
@@ -533,6 +535,35 @@ status:
status: "False"
```
+#### Parent Phase
+
+The top-level `status.phase` reflects the overall instance state:
+
+| Phase | Meaning |
+|---|---|
+| `Initializing` | First deployment — lifecycle tasks running for the first time |
+| `Upgrading` | Image change detected — lifecycle tasks running against new version |
+| `Draining` | Drain strategy active — components being removed before running tasks |
+| `Running` | All enabled components are ready and lifecycle is complete |
+| `Degraded` | One or more components are not fully ready |
+| `Suspended` | `spec.suspend: true` — all reconciliation paused |
+| `Blocked` | Downgrade detected — lifecycle tasks will not run (manual intervention required) |
+| `AwaitingApproval` | Supervised upgrade mode — waiting for approval annotation before proceeding |
+
+#### Lifecycle Phase
+
+The `status.lifecycle.phase` tracks lifecycle task orchestration:
+
+| Phase | Meaning |
+|---|---|
+| `Idle` | No lifecycle work pending |
+| `Draining` | Drain strategy active — waiting for component pods to terminate before running tasks |
+| `Migrating` | Migrate task (`superset db upgrade`) is running |
+| `Initializing` | Init task (`superset init`) is running |
+| `Complete` | All enabled tasks finished successfully |
+| `Blocked` | Downgrade detected — tasks cannot proceed |
+| `AwaitingApproval` | Supervised mode — tasks paused until approval annotation is set |
+
### Child Status
Each child CR reports its own status:
diff --git a/docs/user-guide.md b/docs/user-guide.md
index abe10cf..0adda59 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -365,11 +365,11 @@ Presets control **poolClass**, **poolSize**, and **maxOverflow**:
|---|---|---|---|
| disabled | *(no rendering)* | — | — |
| conservative | NullPool | — | — |
-| balanced (default) | QueuePool | 1 (web/celery), 5 (MCP) | -1 (unlimited) |
-| performance | QueuePool | workers (web), concurrency (celery) | -1 |
-| aggressive | QueuePool | workers × threads (web), concurrency (celery) | -1 |
+| balanced (default) | QueuePool | 1 (web/celery/flower), 5 (MCP) | -1 (unlimited) |
+| performance | QueuePool | workers (web), concurrency (celery), 1 (flower), 10 (MCP) | -1 |
+| aggressive | QueuePool | workers × threads (web), concurrency (celery), 1 (flower), 20 (MCP) | -1 |
-CeleryBeat and Init always use NullPool regardless of preset (singleton/short-lived components with minimal DB interaction).
+CeleryBeat and lifecycle tasks always use NullPool regardless of preset (singleton/short-lived components with minimal DB interaction). CeleryFlower uses standard pool sizing (defaults to 1 for performance/aggressive since it has no worker configuration).
`spec.sqlaEngineOptions` sets the baseline for all Python components. Per-component `sqlaEngineOptions` on `webServer`, `celeryWorker`, `celeryBeat`, `mcpServer`, or `init` replaces the top-level entirely (override semantics, not merge).
@@ -403,6 +403,36 @@ spec:
poolPrePing: true # explicit: overrides static default
```
+### Websocket Server
+
+Enable Superset's async event streaming by setting `websocketServer`. This
+deploys a **Node.js** application (not Python) that pushes real-time updates to
+dashboards via WebSocket connections:
+
+```yaml
+spec:
+ websocketServer: {}
+```
+
+Because the websocket server is Node.js-based, it does **not** receive a
+`superset_config.py`, and the `config` / `sqlaEngineOptions` fields are not
+available on this component. Configuration is handled via environment variables
+on the container template:
+
+```yaml
+spec:
+ websocketServer:
+ podTemplate:
+ container:
+ env:
+ - name: SUPERSET_WEBSERVER_URL
+ value: "http://my-superset-web-server:8088"
+```
+
+The websocket server creates a Service (default port 8088) and supports the
+same scaling, deployment template, and pod template fields as other scalable
+components.
+
### MCP Server
Enable the [Model Context Protocol](https://modelcontextprotocol.io/) server by setting `mcpServer`. This deploys a Python-based FastMCP server that exposes Superset's API via MCP, allowing AI assistants and LLM-based tools to interact with Superset:
@@ -412,7 +442,7 @@ spec:
mcpServer: {}
```
-The MCP server receives a `superset_config.py` with core config (`SECRET_KEY`, structured DB URI if applicable) and top-level/per-component `config` — but not web server port. It runs as a separate Deployment with its own Service.
+The MCP server receives a `superset_config.py` with core config (`SECRET_KEY`, structured DB URI if applicable) and top-level/per-component `config` — but not web server port. It runs as a separate Deployment with its own Service (port 8088). The MCP server supports per-component `sqlaEngineOptions` with higher default pool sizes than other components (5 for balanced, 10 for performance, 20 for aggressive) to accommodate concurrent tool invocations.
### Lifecycle Configuration
@@ -445,8 +475,30 @@ The `upgradeMode` field controls how image upgrades are handled:
- **Automatic** (default) — tasks run immediately when an image change is detected
- **Supervised** — tasks wait for an annotation-based approval before running
+```yaml
+spec:
+ lifecycle:
+ upgradeMode: Supervised
+```
+
+When an image change is detected in supervised mode, the operator sets
+`status.phase: AwaitingApproval` and records the upgrade context in
+`status.lifecycle.upgrade`. Approve the upgrade by annotating the CR:
+
+```bash
+kubectl annotate superset my-superset superset.apache.org/approve-upgrade=true
+```
+
+The operator clears the annotation automatically after lifecycle tasks complete.
+You can monitor the upgrade status with:
+
+```bash
+kubectl get superset my-superset -o jsonpath='{.status.lifecycle}'
+```
+
The operator also performs semver comparison on image tags and blocks downgrades
-to prevent accidental database corruption.
+to prevent accidental database corruption. A blocked downgrade sets
+`status.phase: Blocked` — revert the image tag to resolve.
#### Upgrade Strategy
@@ -494,6 +546,41 @@ on `podTemplate`; env, resources, securityContext, etc. on
`podTemplate.container`), so task pods inherit top-level scheduling and security
settings and can be customized independently.
+#### Timeout, Retries, and Pod Retention
+
+Each task has configurable timeout and retry behavior:
+
+```yaml
+spec:
+ lifecycle:
+ podRetention:
+ policy: RetainOnFailure # Delete (default) | Retain | RetainOnFailure
+ migrate:
+ timeout: 10m # max time per attempt (default: 5m)
+ maxRetries: 5 # attempts before permanent failure (default: 3)
+ init:
+ timeout: 5m
+ maxRetries: 3
+```
+
+On failure, the operator retries with exponential backoff (`10s * 2^(attempt-1)`,
+capped at 5m). If a pod exceeds the timeout while Running or Pending, it counts
+as a failed attempt.
+
+Pod retention controls what happens to task pods after completion:
+
+| Policy | On Success | On Failure |
+|---|---|---|
+| `Delete` (default) | Pod deleted | Pod deleted |
+| `Retain` | Pod kept | Pod kept |
+| `RetainOnFailure` | Pod deleted | Pod kept for debugging |
+
+Use `RetainOnFailure` to inspect logs of failed migrations:
+
+```bash
+kubectl logs <pod-name> -c superset
+```
+
#### Admin User (Dev Mode Only)
In dev mode, the operator can create an admin user during initialization:
@@ -955,7 +1042,11 @@ spec:
forceReload: "2026-03-14T12:00:00Z"
```
-Change the value to any new string to trigger a restart.
+Change the value to any new string to trigger a restart. This is primarily
+useful for **secret rotation**: when you update a Kubernetes Secret's data, pods
+don't automatically restart because the operator references secrets via
+`valueFrom.secretKeyRef` (resolved at pod creation time). Changing `forceReload`
+forces new pods that pick up the updated secret values.
## Suspend Reconciliation