feat(api): combined-image mode + imagePullSecrets passthrough; restructure DocumentDBSpec with spec.advanced stanza

.github/actions/setup-test-environment/action.yml

@@ -707,8 +707,9 @@ runs:
         spec:
           nodeCount: ${{ inputs.node-count }}
           instancesPerNode: ${{ inputs.instances-per-node }}
-          documentDBImage: ${DOCUMENTDB_IMAGE_RESOLVED}
-          gatewayImage: ${GATEWAY_IMAGE_RESOLVED}
+          image:
+            documentDB: ${DOCUMENTDB_IMAGE_RESOLVED}
+            gateway: ${GATEWAY_IMAGE_RESOLVED}
           resource:
             storage:
               pvcSize: 5Gi

CHANGELOG.md

@@ -10,6 +10,7 @@
 - **Two-Phase Extension Upgrade**: New `spec.schemaVersion` field separates binary upgrades (`spec.documentDBVersion`) from irreversible schema migrations (`ALTER EXTENSION UPDATE`). The default behavior gives you a rollback-safe window — update the binary first, validate, then finalize the schema. Set `schemaVersion: "auto"` for single-step upgrades in development environments. See the [upgrade guide](docs/operator-public-documentation/preview/operations/upgrades.md) for details.
 
 ### Breaking Changes
+- **CRD restructure into domain-grouped stanzas**: image, postgres and plugin fields have moved into dedicated groups. Migrate as follows: `spec.documentDBImage` → `spec.image.documentDB`, `spec.gatewayImage` → `spec.image.gateway`, `spec.postgresImage` → `spec.image.postgres`, `spec.sidecarInjectorPluginName` → `spec.plugins.sidecarInjectorName`. A new `spec.image.mode` enum (`layered` | `combined`, default `layered`) replaces the previous implicit "empty documentDBImage means layered" heuristic. A new `spec.postgres` group exposes `uid`, `gid`, `preloadLibraries` and `postInitSQL` (the operator's mandatory bootstrap statements always run first; user statements are appended after). A new root-level `spec.imagePullSecrets` is propagated to the underlying CNPG cluster.
 - **Validating webhook added**: A new `ValidatingWebhookConfiguration` enforces that `spec.schemaVersion` never exceeds the binary version and blocks `spec.documentDBVersion` rollbacks below the committed schema version. This requires [cert-manager](https://cert-manager.io/) to be installed in the cluster (it is already a prerequisite for the sidecar injector). Existing clusters upgrading to this release will have the webhook activated automatically via `helm upgrade`.
 - **Removed `Disabled` TLS gateway mode**: The `spec.tls.gateway.mode: Disabled` option has been removed to eliminate the security risk of plaintext Mongo wire protocol traffic. Previously, `Disabled` mode served connections in plaintext, contradicting the `Disabled` tab in `tls.md` which described the mode as a self-signed bootstrap. Empty or unset mode now defaults to `SelfSigned`, and the controller fails closed (also defaulting to `SelfSigned`) if a legacy `Disabled` value is encountered on a stored object. Users with `mode: Disabled` should remove this setting or explicitly set `mode: SelfSigned` — the gateway will automatically use a cert-manager generated self-signed certificate. See [issue #356](https://github.com/documentdb/documentdb-kubernetes-operator/issues/356) for details.
 
@@ -38,7 +39,7 @@
 ### Breaking Changes
 - **Kubernetes 1.35+ required**: The legacy combined-image deployment mode for Kubernetes < 1.35 has been removed. Kubernetes 1.35+ is now required.
 - **Deb-based container images**: Container images switched from source-compiled builds to deb-based packages under `ghcr.io/documentdb/documentdb-kubernetes-operator/`. The extension and gateway are now separate images with versioned tags (e.g., `:0.109.0`).
-- **PostgreSQL base image changed to Debian trixie**: The default `postgresImage` changed from `postgresql:18-minimal-bookworm` to `postgresql:18-minimal-trixie` (Debian 13) to satisfy the deb-based extension's GLIBC requirements. Existing clusters that don't explicitly set `postgresImage` will use the new base on upgrade.
+- **PostgreSQL base image changed to Debian trixie**: The default `image.postgres` changed from `postgresql:18-minimal-bookworm` to `postgresql:18-minimal-trixie` (Debian 13) to satisfy the deb-based extension's GLIBC requirements. Existing clusters that don't explicitly set `image.postgres` will use the new base on upgrade.
 
 ### Bug Fixes
 - Gateway pods now restart when TLS secret name changes

docs/designs/image-management.md

@@ -88,7 +88,7 @@ The operator binary determines which database images to use through a priority c
 
 ```
 Priority (highest → lowest):
-1. spec.documentDBImage          ← CR field: full image URI override
+1. spec.image.documentDB          ← CR field: full image URI override
 2. spec.documentDBVersion        ← CR field: used as tag with hardcoded repo
 3. env DOCUMENTDB_VERSION        ← from Helm chart (documentDbVersion in values.yaml)
 4. ChangeStreams feature gate     ← temporary override for changestream images
@@ -99,7 +99,7 @@ Priority (highest → lowest):
 
 ```
 Priority (highest → lowest):
-1. spec.gatewayImage             ← CR field: full image URI override
+1. spec.image.gateway             ← CR field: full image URI override
 2. spec.documentDBVersion        ← CR field: used as tag with hardcoded repo
 3. env DOCUMENTDB_VERSION        ← from Helm chart (documentDbVersion in values.yaml)
 4. ChangeStreams feature gate     ← temporary override for changestream images
@@ -108,7 +108,7 @@ Priority (highest → lowest):
 
 ### PostgreSQL Image
 
-Set via `spec.postgresImage` in the DocumentDB CR. Defaults to `ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie` (hardcoded in the CRD schema).
+Set via `spec.image.postgres` in the DocumentDB CR. Defaults to `ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie` (hardcoded in the CRD schema).
 
 ### How Images Flow into Pods
 

docs/developer-guides/sidecar-injector-plugin-configuration.md

@@ -42,7 +42,8 @@ spec:
     storage:
       pvcSize: "10Gi"
   # Explicitly specify gateway image
-  gatewayImage: "ghcr.io/microsoft/documentdb/documentdb-local:17"
+  image:
+    gateway: "ghcr.io/microsoft/documentdb/documentdb-local:17"
   exposeViaService:
     serviceType: "ClusterIP"
 ```
@@ -111,7 +112,8 @@ spec:
   resource:
     storage:
       pvcSize: "10Gi"
-  gatewayImage: "ghcr.io/microsoft/documentdb/documentdb-local:17"
+  image:
+    gateway: "ghcr.io/microsoft/documentdb/documentdb-local:17"
 ```
 
 ### Advanced Configuration (All Parameters)
@@ -127,8 +129,10 @@ spec:
   resource:
     storage:
       pvcSize: "20Gi"
-  gatewayImage: "ghcr.io/microsoft/documentdb/documentdb-local:17"
-  sidecarInjectorPluginName: "cnpg-i-sidecar-injector.documentdb.io"
+  image:
+    gateway: "ghcr.io/microsoft/documentdb/documentdb-local:17"
+  plugins:
+    sidecarInjectorName: "cnpg-i-sidecar-injector.documentdb.io"
   exposeViaService:
     serviceType: "LoadBalancer"
 ```