stackabletech · sbernauer · Nov 21, 2025 · maltesander · Nov 21, 2025 · maltesander
diff --git a/modules/concepts/pages/overrides.adoc b/modules/concepts/pages/overrides.adoc
@@ -151,6 +151,58 @@ They will *not* be applied to:
 
 * Jobs, that are used to setup systems the product depends on e.g. create a database schema for Superset or Airflow.
 
+[#object-overrides]
+== Object overrides
+
+Sometime you need to override Kubernetes objects other than the generated Pods, e.g. ServiceAccounts or the StatefulSet/Deployment/DaemonSet.
-Sometime you need to override Kubernetes objects other than the generated Pods, e.g. ServiceAccounts or the StatefulSet/Deployment/DaemonSet.
+Sometimes you need to override Kubernetes objects other than the generated Pods, e.g. ServiceAccounts or the StatefulSet/Deployment/DaemonSet.
-Sometime you need to override Kubernetes objects other than the generated Pods, e.g. ServiceAccounts or the StatefulSet/Deployment/DaemonSet.
+Sometimes you need to override Kubernetes objects other than the generated Pods, e.g. ServiceAccounts or the StatefulSet/Deployment/DaemonSet.
+Object overrides allow you to override any Kubernetes object the operator creates are part of it's reconciliation loop, which basically means all objects that are created for a given stacklet.
-Object overrides allow you to override any Kubernetes object the operator creates are part of it's reconciliation loop, which basically means all objects that are created for a given stacklet.
+Object overrides let you modify any Kubernetes resource that the operator creates as part of its reconciliation loop, which essentially includes all objects associated with a given stacklet.
-Object overrides allow you to override any Kubernetes object the operator creates are part of it's reconciliation loop, which basically means all objects that are created for a given stacklet.
+Object overrides let you modify any Kubernetes resource that the operator creates as part of its reconciliation loop, which essentially includes all objects associated with a given stacklet.
+
+On every Stackable CRD that get's reconciled into a set of Kubernetes objects we offer a field `.spec.objectOverrides`.
-On every Stackable CRD that get's reconciled into a set of Kubernetes objects we offer a field `.spec.objectOverrides`.
+On every Stackable CRD that is reconciled into a set of Kubernetes objects we provide the field `.spec.objectOverrides`.
-On every Stackable CRD that get's reconciled into a set of Kubernetes objects we offer a field `.spec.objectOverrides`.
+On every Stackable CRD that is reconciled into a set of Kubernetes objects we provide the field `.spec.objectOverrides`.
+You can set it to a list of arbitrary YAML objects, which need to be valid Kubernetes objects.
-You can set it to a list of arbitrary YAML objects, which need to be valid Kubernetes objects.
+This field accepts a list of arbitrary YAML objects, each of which must be a valid Kubernetes resource.
-You can set it to a list of arbitrary YAML objects, which need to be valid Kubernetes objects.
+This field accepts a list of arbitrary YAML objects, each of which must be a valid Kubernetes resource.
+
+For every object it creates, the operator will walk the list of overrides from top to bottom.
+It will than first check if the override matches the object being created using apiVersion, kind, name and namespace (if set - doesn't need to be the case for cluster scoped objects).
+If the override matches, it will be merged in the same way Pod overrides are merged, using the merge algorithm described in the {k8s-openapi-deepmerge}[k8s-openapi docs{external-link-icon}^], which basically tries to mimic the way Kubernetes merges patches onto objects.
+
+A consequence of this is, that you can only modify objects the operator creates, and not deploy any additional arbitrary objects.
-For every object it creates, the operator will walk the list of overrides from top to bottom.
-It will than first check if the override matches the object being created using apiVersion, kind, name and namespace (if set - doesn't need to be the case for cluster scoped objects).
-If the override matches, it will be merged in the same way Pod overrides are merged, using the merge algorithm described in the {k8s-openapi-deepmerge}[k8s-openapi docs{external-link-icon}^], which basically tries to mimic the way Kubernetes merges patches onto objects.
-
-A consequence of this is, that you can only modify objects the operator creates, and not deploy any additional arbitrary objects.
+For every resource it creates, the operator processes the list of overrides from top to bottom.
+It first checks if an override matches the resource being created by comparing the `apiVersion`, `kind`, `name` and if applicable `namespace` (cluster-scoped resources may omit the namespace).
+If an override matches, it is merged using the same mechanism as Pod overrides, using the merge algorithm described in the {k8s-openapi-deepmerge}[k8s-openapi docs{external-link-icon}^], which closely mimics the way Kubernetes applies patches to resources.
+
+As a result, you can only modify resources created by the operator. This mechanism does not work to deploy any additional arbitrary Kubernetes resources.
-For every object it creates, the operator will walk the list of overrides from top to bottom.
-It will than first check if the override matches the object being created using apiVersion, kind, name and namespace (if set - doesn't need to be the case for cluster scoped objects).
-If the override matches, it will be merged in the same way Pod overrides are merged, using the merge algorithm described in the {k8s-openapi-deepmerge}[k8s-openapi docs{external-link-icon}^], which basically tries to mimic the way Kubernetes merges patches onto objects.
-
-A consequence of this is, that you can only modify objects the operator creates, and not deploy any additional arbitrary objects.
+For every resource it creates, the operator processes the list of overrides from top to bottom.
+It first checks if an override matches the resource being created by comparing the `apiVersion`, `kind`, `name` and if applicable `namespace` (cluster-scoped resources may omit the namespace).
+If an override matches, it is merged using the same mechanism as Pod overrides, using the merge algorithm described in the {k8s-openapi-deepmerge}[k8s-openapi docs{external-link-icon}^], which closely mimics the way Kubernetes applies patches to resources.
+
+As a result, you can only modify resources created by the operator. This mechanism does not work to deploy any additional arbitrary Kubernetes resources.
+
+[source,yaml]
+----
+apiVersion: zookeeper.stackable.tech/v1alpha1
+kind: ZookeeperCluster
+metadata:
+  name: simple-zk
+spec:
+  # ...
+  objectOverrides:
+    - apiVersion: apps/v1
+      kind: StatefulSet
+      metadata:
+        name: simple-zk-server-default
+        namespace: default
+        labels:
+          custom: label
+      spec:
+        replicas: 2
+        podManagementPolicy: Parallel
+    - apiVersion: v1
+      kind: ServiceAccount
+      metadata:
+        name: simple-zk-serviceaccount
+        namespace: default
+        labels:
+          im-on: AWS
+        annotations:
+          custom: AWS
+    - apiVersion: policy/v1
+      kind: PodDisruptionBudget
+      metadata:
+        name: simple-zk-server
+        namespace: default
+      spec:
+        maxUnavailable: 42
+----
+
 [#jvm-argument-overrides]
 == JVM argument overrides