wip

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>

Author: csviri

docs/content/en/docs/documentation/features.md

@@ -23,14 +23,6 @@ public class DeploymentReconciler
 }
 ```
 
-## Leader Election
-
-Operators are typically deployed with a single active instance. However, you can deploy multiple instances where only one (the "leader") processes events. This is achieved through "leader election."
-
-While all instances run and start their event sources to populate caches, only the leader processes events. If the leader crashes, other instances are already warmed up and ready to take over when a new leader is elected.
-
-See sample configuration in the [E2E test](https://github.com/java-operator-sdk/java-operator-sdk/blob/8865302ac0346ee31f2d7b348997ec2913d5922b/sample-operators/leader-election/src/main/java/io/javaoperatorsdk/operator/sample/LeaderElectionTestOperator.java#L21-L23).
-
 ## Automatic CRD Generation
 
 **Note:** This feature is provided by the [Fabric8 Kubernetes Client](https://github.com/fabric8io/kubernetes-client), not JOSDK itself.

docs/content/en/docs/documentation/operations/leader-election.md

@@ -0,0 +1,72 @@
+---
+title: Leader Election
+weight: 89
+---
+
+When running multiple replicas of an operator for high availability, leader election ensures that
+only one instance actively reconciles resources at a time. JOSDK uses Kubernetes
+[Lease](https://kubernetes.io/docs/concepts/architecture/leases/) objects for leader election.
+
+## Enabling Leader Election
+
+### Programmatic Configuration
+
+```java
+var operator = new Operator(o -> o.withLeaderElectionConfiguration(
+    new LeaderElectionConfiguration("my-operator-lease", "operator-namespace")));
+```
+
+Or using the builder for full control:
+
+```java
+import static io.javaoperatorsdk.operator.api.config.LeaderElectionConfigurationBuilder.aLeaderElectionConfiguration;
+
+var config = aLeaderElectionConfiguration("my-operator-lease")
+    .withLeaseNamespace("operator-namespace")
+    .withIdentity(System.getenv("POD_NAME"))
+    .withLeaseDuration(Duration.ofSeconds(15))
+    .withRenewDeadline(Duration.ofSeconds(10))
+    .withRetryPeriod(Duration.ofSeconds(2))
+    .build();
+
+var operator = new Operator(o -> o.withLeaderElectionConfiguration(config));
+```
+
+### External Configuration
+
+Leader election can also be configured via properties (e.g. environment variables or a config file).
+
+See details under [configurations](configuration.md) page.
+
+## How It Works
+
+1. When leader election is enabled, the operator starts but **does not process events** until it acquires
+   the lease.
+2. Once leadership is acquired, event processing begins normally.
+3. If leadership is lost (e.g. the leader pod becomes unresponsive), another instance acquires the lease
+   and takes over reconciliation. The instance that lost the lead is terminated (`System.exit()`)
+
+### Identity and Namespace Inference
+
+If not explicitly set:
+- **Identity** is resolved from the `HOSTNAME` environment variable, then the pod name, falling back to a
+  random UUID.
+- **Lease namespace** defaults to the namespace the operator pod is running in.
+
+## RBAC Requirements
+
+The operator's service account needs permissions to manage Lease objects:
+
+```yaml
+- apiGroups: ["coordination.k8s.io"]
+  resources: ["leases"]
+  verbs: ["create", "update", "get"]
+```
+
+JOSDK checks for these permissions at startup and throws a clear error if they are missing.
+
+## Sample E2E Test
+
+A complete working example is available in the
+[`leader-election` sample operator](https://github.com/java-operator-sdk/java-operator-sdk/tree/main/sample-operators/leader-election),
+including multi-replica deployment manifests and an E2E test that verifies failover behavior.