docs(release): prepare 0.3.0 docs and notes

api/v1alpha1/openbaocluster_types.go

@@ -703,8 +703,10 @@ type UpgradeConfig struct {
 	// The role must bind to the upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount),
 	// which is automatically created by the operator.
 	//
-	// If OIDC is enabled in SelfInit and this field is empty, a default role
-	// named "openbao-operator-upgrade" will be assumed/created.
+	// If OIDC is enabled during initial SelfInit bootstrap and this field is
+	// empty, a default role named "openbao-operator-upgrade" will be created.
+	// For already-initialized clusters, configure this role explicitly or keep
+	// the default role created during initial bootstrap.
 	//
 	// This is the supported authentication mechanism for built-in upgrade orchestration.
 	// +optional
@@ -713,9 +715,9 @@ type UpgradeConfig struct {
 	// token for future non-JWT upgrade authentication flows.
 	//
 	// Built-in rolling and blue/green upgrade orchestration does not support
-	// token-based authentication. Configure spec.upgrade.jwtAuthRole or enable
-	// spec.selfInit.oidc.enabled instead.
-	// +kubebuilder:validation:XValidation:rule="self == null",message="spec.upgrade.tokenSecretRef is not supported; configure spec.upgrade.jwtAuthRole or enable spec.selfInit.oidc.enabled"
+	// token-based authentication. Configure spec.upgrade.jwtAuthRole, or use the
+	// default role created during initial spec.selfInit.oidc bootstrap.
+	// +kubebuilder:validation:XValidation:rule="self == null",message="spec.upgrade.tokenSecretRef is not supported; configure spec.upgrade.jwtAuthRole or use the default role created during initial spec.selfInit.oidc bootstrap"
 	// +optional
 	TokenSecretRef *corev1.LocalObjectReference `json:"tokenSecretRef,omitempty"`
 
@@ -2081,9 +2083,10 @@ type OpenBaoClusterSpec struct {
 	//
 	// Built-in upgrade executor Jobs authenticate with JWT auth using the
 	// upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount). If
-	// spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty,
-	// the operator assumes or bootstraps the default "openbao-operator-upgrade"
-	// role.
+	// spec.selfInit.oidc.enabled is true during initial SelfInit bootstrap and
+	// spec.upgrade.jwtAuthRole is empty, the operator creates the default
+	// "openbao-operator-upgrade" role. Already-initialized clusters must keep
+	// that role or configure spec.upgrade.jwtAuthRole explicitly.
 	//
 	// Pre-upgrade snapshots use spec.backup configuration and backup
 	// authentication rather than spec.upgrade credentials.

charts/openbao-operator/crds/openbao.org_openbaoclusters.yaml

@@ -4579,9 +4579,10 @@ spec:
 
                   Built-in upgrade executor Jobs authenticate with JWT auth using the
                   upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount). If
-                  spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty,
-                  the operator assumes or bootstraps the default "openbao-operator-upgrade"
-                  role.
+                  spec.selfInit.oidc.enabled is true during initial SelfInit bootstrap and
+                  spec.upgrade.jwtAuthRole is empty, the operator creates the default
+                  "openbao-operator-upgrade" role. Already-initialized clusters must keep
+                  that role or configure spec.upgrade.jwtAuthRole explicitly.
 
                   Pre-upgrade snapshots use spec.backup configuration and backup
                   authentication rather than spec.upgrade credentials.
@@ -4708,8 +4709,10 @@ spec:
                       The role must bind to the upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount),
                       which is automatically created by the operator.
 
-                      If OIDC is enabled in SelfInit and this field is empty, a default role
-                      named "openbao-operator-upgrade" will be assumed/created.
+                      If OIDC is enabled during initial SelfInit bootstrap and this field is
+                      empty, a default role named "openbao-operator-upgrade" will be created.
+                      For already-initialized clusters, configure this role explicitly or keep
+                      the default role created during initial bootstrap.
 
                       This is the supported authentication mechanism for built-in upgrade orchestration.
                     type: string
@@ -4775,8 +4778,8 @@ spec:
                       token for future non-JWT upgrade authentication flows.
 
                       Built-in rolling and blue/green upgrade orchestration does not support
-                      token-based authentication. Configure spec.upgrade.jwtAuthRole or enable
-                      spec.selfInit.oidc.enabled instead.
+                      token-based authentication. Configure spec.upgrade.jwtAuthRole, or use the
+                      default role created during initial spec.selfInit.oidc bootstrap.
                     properties:
                       name:
                         default: ""
@@ -4791,7 +4794,8 @@ spec:
                     x-kubernetes-map-type: atomic
                     x-kubernetes-validations:
                     - message: spec.upgrade.tokenSecretRef is not supported; configure
-                        spec.upgrade.jwtAuthRole or enable spec.selfInit.oidc.enabled
+                        spec.upgrade.jwtAuthRole or use the default role created during
+                        initial spec.selfInit.oidc bootstrap
                       rule: self == null
                 type: object
               version:

config/crd/bases/openbao.org_openbaoclusters.yaml

@@ -4578,9 +4578,10 @@ spec:
 
                   Built-in upgrade executor Jobs authenticate with JWT auth using the
                   upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount). If
-                  spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty,
-                  the operator assumes or bootstraps the default "openbao-operator-upgrade"
-                  role.
+                  spec.selfInit.oidc.enabled is true during initial SelfInit bootstrap and
+                  spec.upgrade.jwtAuthRole is empty, the operator creates the default
+                  "openbao-operator-upgrade" role. Already-initialized clusters must keep
+                  that role or configure spec.upgrade.jwtAuthRole explicitly.
 
                   Pre-upgrade snapshots use spec.backup configuration and backup
                   authentication rather than spec.upgrade credentials.
@@ -4707,8 +4708,10 @@ spec:
                       The role must bind to the upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount),
                       which is automatically created by the operator.
 
-                      If OIDC is enabled in SelfInit and this field is empty, a default role
-                      named "openbao-operator-upgrade" will be assumed/created.
+                      If OIDC is enabled during initial SelfInit bootstrap and this field is
+                      empty, a default role named "openbao-operator-upgrade" will be created.
+                      For already-initialized clusters, configure this role explicitly or keep
+                      the default role created during initial bootstrap.
 
                       This is the supported authentication mechanism for built-in upgrade orchestration.
                     type: string
@@ -4774,8 +4777,8 @@ spec:
                       token for future non-JWT upgrade authentication flows.
 
                       Built-in rolling and blue/green upgrade orchestration does not support
-                      token-based authentication. Configure spec.upgrade.jwtAuthRole or enable
-                      spec.selfInit.oidc.enabled instead.
+                      token-based authentication. Configure spec.upgrade.jwtAuthRole, or use the
+                      default role created during initial spec.selfInit.oidc bootstrap.
                     properties:
                       name:
                         default: ""
@@ -4790,7 +4793,8 @@ spec:
                     x-kubernetes-map-type: atomic
                     x-kubernetes-validations:
                     - message: spec.upgrade.tokenSecretRef is not supported; configure
-                        spec.upgrade.jwtAuthRole or enable spec.selfInit.oidc.enabled
+                        spec.upgrade.jwtAuthRole or use the default role created during
+                        initial spec.selfInit.oidc bootstrap
                       rule: self == null
                 type: object
               version:

docs/reference/api.md

@@ -1038,7 +1038,7 @@ _Appears in:_
 | `auditFileStorage` _[AuditFileStorageConfig](#auditfilestorageconfig)_ | AuditFileStorage configures a shared filesystem integration point for file audit devices.<br />When configured, file audit device paths must be under auditFileStorage.mountPath. |  | Optional: \{\} <br /> |
 | `plugins` _[Plugin](#plugin) array_ | Plugins configures declarative plugins for the OpenBao cluster.<br />See: https://openbao.org/docs/configuration/plugins/ |  | Optional: \{\} <br /> |
 | `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry configures telemetry reporting for the OpenBao cluster.<br />See: https://openbao.org/docs/configuration/telemetry/ |  | Optional: \{\} <br /> |
-| `upgrade` _[UpgradeConfig](#upgradeconfig)_ | Upgrade configures upgrade operations.<br />Built-in upgrade executor Jobs authenticate with JWT auth using the<br />upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount). If<br />spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty,<br />the operator assumes or bootstraps the default "openbao-operator-upgrade"<br />role.<br />Pre-upgrade snapshots use spec.backup configuration and backup<br />authentication rather than spec.upgrade credentials. |  | Optional: \{\} <br /> |
+| `upgrade` _[UpgradeConfig](#upgradeconfig)_ | Upgrade configures upgrade operations.<br />Built-in upgrade executor Jobs authenticate with JWT auth using the<br />upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount). If<br />spec.selfInit.oidc.enabled is true during initial SelfInit bootstrap and<br />spec.upgrade.jwtAuthRole is empty, the operator creates the default<br />"openbao-operator-upgrade" role. Already-initialized clusters must keep<br />that role or configure spec.upgrade.jwtAuthRole explicitly.<br />Pre-upgrade snapshots use spec.backup configuration and backup<br />authentication rather than spec.upgrade credentials. |  | Optional: \{\} <br /> |
 | `unseal` _[UnsealConfig](#unsealconfig)_ | Unseal defines the auto-unseal configuration.<br />If omitted, defaults to "static" mode managed by the operator. |  | Optional: \{\} <br /> |
 | `imageVerification` _[ImageVerificationConfig](#imageverificationconfig)_ | ImageVerification configures supply chain security checks. |  | Optional: \{\} <br /> |
 | `operatorImageVerification` _[ImageVerificationConfig](#imageverificationconfig)_ | OperatorImageVerification configures supply chain security checks for operator-managed helper images<br />(init container, backup/upgrade/restore executors). These images are typically signed<br />by the operator project (e.g., dc-tec/openbao-operator) rather than the OpenBao upstream project.<br />If omitted, helper image verification does not fall back to ImageVerification.<br />In Development, omitted means disabled. In Hardened, omitted means enabled. |  | Optional: \{\} <br /> |
@@ -2026,8 +2026,8 @@ _Appears in:_
 | --- | --- | --- | --- |
 | `image` _string_ | Image is the container image to use for upgrade operations.<br />This image is used by Kubernetes Jobs created during upgrades (for example, blue/green<br />cluster orchestration actions). The executor runs inside the tenant namespace and<br />authenticates to OpenBao using a projected ServiceAccount token (JWT auth).<br />If not specified, defaults to "&lt;repo&gt;:X.Y.Z" where &lt;repo&gt; is derived from OPERATOR_UPGRADE_IMAGE_REPOSITORY<br />(default: "ghcr.io/dc-tec/openbao-upgrade") and the tag matches OPERATOR_VERSION. |  | Optional: \{\} <br /> |
 | `preUpgradeSnapshot` _boolean_ | PreUpgradeSnapshot, when true, triggers a backup before any upgrade.<br />When enabled, the upgrade manager will create a backup using the backup<br />configuration (spec.backup.target, spec.backup.image, etc.) and<br />wait for it to complete before proceeding with the upgrade.<br />If the backup fails, the upgrade will be blocked and a Degraded condition<br />will be set with Reason=PreUpgradeBackupFailed.<br />Requires spec.backup to be configured with target, image, and<br />authentication (jwtAuthRole or tokenSecretRef). |  | Optional: \{\} <br /> |
-| `jwtAuthRole` _string_ | JWTAuthRole is the name of the JWT Auth role configured in OpenBao<br />for upgrade executor Jobs. The executor authenticates with a projected<br />ServiceAccount token from &lt;cluster-name&gt;-upgrade-serviceaccount.<br />The role must be configured in OpenBao and must grant the permissions<br />required by the selected upgrade strategy, including:<br />- "read" capability on sys/health<br />- "sudo" and "update" capability on sys/step-down<br />- "read" capability on sys/storage/raft/autopilot/state<br />- for Blue/Green, raft join/configuration/remove-peer/promote/demote operations<br />The role must bind to the upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount),<br />which is automatically created by the operator.<br />If OIDC is enabled in SelfInit and this field is empty, a default role<br />named "openbao-operator-upgrade" will be assumed/created.<br />This is the supported authentication mechanism for built-in upgrade orchestration. |  | Optional: \{\} <br /> |
-| `tokenSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | TokenSecretRef optionally references a Secret containing an OpenBao API<br />token for future non-JWT upgrade authentication flows.<br />Built-in rolling and blue/green upgrade orchestration does not support<br />token-based authentication. Configure spec.upgrade.jwtAuthRole or enable<br />spec.selfInit.oidc.enabled instead. |  | Optional: \{\} <br /> |
+| `jwtAuthRole` _string_ | JWTAuthRole is the name of the JWT Auth role configured in OpenBao<br />for upgrade executor Jobs. The executor authenticates with a projected<br />ServiceAccount token from &lt;cluster-name&gt;-upgrade-serviceaccount.<br />The role must be configured in OpenBao and must grant the permissions<br />required by the selected upgrade strategy, including:<br />- "read" capability on sys/health<br />- "sudo" and "update" capability on sys/step-down<br />- "read" capability on sys/storage/raft/autopilot/state<br />- for Blue/Green, raft join/configuration/remove-peer/promote/demote operations<br />The role must bind to the upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount),<br />which is automatically created by the operator.<br />If OIDC is enabled during initial SelfInit bootstrap and this field is<br />empty, a default role named "openbao-operator-upgrade" will be created.<br />For already-initialized clusters, configure this role explicitly or keep<br />the default role created during initial bootstrap.<br />This is the supported authentication mechanism for built-in upgrade orchestration. |  | Optional: \{\} <br /> |
+| `tokenSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | TokenSecretRef optionally references a Secret containing an OpenBao API<br />token for future non-JWT upgrade authentication flows.<br />Built-in rolling and blue/green upgrade orchestration does not support<br />token-based authentication. Configure spec.upgrade.jwtAuthRole, or use the<br />default role created during initial spec.selfInit.oidc bootstrap. |  | Optional: \{\} <br /> |
 | `strategy` _[UpdateStrategyType](#updatestrategytype)_ | Strategy defines the update strategy to use. | RollingUpdate | Enum: [RollingUpdate BlueGreen] <br /> |
 | `requests` _[UpgradeRequestConfig](#upgraderequestconfig)_ | Requests defines explicit one-shot operator requests for the current<br />upgrade workflow. The operator acts only when a request value changes. |  | Optional: \{\} <br /> |
 | `blueGreen` _[BlueGreenConfig](#bluegreenconfig)_ | BlueGreen configures the behavior when Strategy is BlueGreen. |  | Optional: \{\} <br /> |

docs/reference/compatibility.md

@@ -41,7 +41,7 @@ The current stable release line is intended for real deployments, but it remains
       emphasis: 'caution',
     },
     {
-      cells: ['v1.33', 'Not validated for the current release line', 'May work but is not release-gated for 0.2.0', 'Validate in staging before carrying this version into the current pre-GA line'],
+      cells: ['v1.33', 'Not validated for the current release line', 'May work but is not release-gated for the current line', 'Validate in staging before carrying this version into the current pre-GA line'],
       emphasis: 'caution',
     },
     {

docs/reference/known-limitations.md

@@ -35,7 +35,7 @@ journey: reference
       cells: ['Helm CRD lifecycle', 'Helm does not automatically upgrade or delete CRDs.', 'Use release `crds.yaml` assets for CRD lifecycle operations.'],
     },
     {
-      cells: ['Built-in upgrade authentication', 'Built-in rolling and blue/green upgrade orchestration do not support `spec.upgrade.tokenSecretRef`; upgrade Jobs use JWT authentication only.', 'Configure `spec.upgrade.jwtAuthRole` or enable `spec.selfInit.oidc.enabled` so the operator can bootstrap the upgrade auth path.'],
+      cells: ['Built-in upgrade authentication', 'Built-in rolling and blue/green upgrade orchestration do not support `spec.upgrade.tokenSecretRef`; upgrade Jobs use JWT authentication only.', 'Configure `spec.upgrade.jwtAuthRole`, or use the default role created during initial `selfInit.oidc` bootstrap.'],
     },
     {
       cells: ['Audit file storage archival', '`spec.auditFileStorage` provides a PVC-backed collector handoff and replay buffer; it does not provide rotation, pruning, tamper-proof retention, or a collector.', 'Mount the audit PVC read-only into a collector and ship records to external retention-controlled storage.'],