From 2e8ac31c8a18a4cb86ff6f58d75647a4faabb19a Mon Sep 17 00:00:00 2001
From: Sebastian Bernauer <sebastian.bernauer@stackable.tech>
Date: Fri, 21 Nov 2025 10:38:20 +0100
Subject: [PATCH] Add objectOverrides concepts page

---
 modules/concepts/pages/overrides.adoc | 52 +++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/modules/concepts/pages/overrides.adoc b/modules/concepts/pages/overrides.adoc
index 94a497bfa..da0d61f42 100644
--- 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.
+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.
+
+On every Stackable CRD that get's reconciled into a set of Kubernetes objects we offer a field `.spec.objectOverrides`.
+You can set it to a list of arbitrary YAML objects, which need to be valid Kubernetes 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.
+
+[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