Add leaderelection docs

docs/en/ingest-management/elastic-agent/elastic-agent-providers.asciidoc

@@ -194,6 +194,67 @@ This means that anyone who have access to Agent Pod (`kubectl exec` for example)
 access Kubernetes Secrets API and get a specific secret no matter which namespace it belongs to.
 In this, this option should be carefully considered.
 
+[discrete]
+[[kubernetes_leaderelection-provider]]
+==== Kubernetes LeaderElection Provider
+
+Provides the option to enable leaderelection between a set of Agents
+running on Kubernetes. Only one Agent at a time will be the holder of the leader
+lock and based on this, configurations can be enabled with the condition
+that the Agent holds the leadership. This can be useful in cases where we want
+only Agent between a set of Agents to collect cluster wide metrics for the
+Kubernetes cluster like from `kube-state-metrics` endpoint.
+
+Provider needs a `kubeconfig` file so as to establish connection to Kubernetes API,
+or it can automatically reach the API if it runs in an inCluster environment (Agent runs as Pod).
+
+[source,yaml]
+----
+providers.kubernetes_leaderelection:
+  #kube_config: /Users/elastic-agent/.kube/config
+  #leader_lease: agent-k8s-leader-lock
+----
+
+`kube_config`:: (Optional) Use given config file as configuration for Kubernetes
+client. If kube_config is not set, KUBECONFIG environment variable will be
+checked and if not present it will fall back to InCluster.
+`leader_lease`:: (Optional) Specify the name of the leader lease.
+By default it is `elastic-agent-cluster-leader`.
+
+The available key is:
+
+|===
+|Key |Type |Description
+
+|`kubernetes_leaderelection.leader`
+|`bool`
+|The value of the leadership flag. It is `true` when the Agent is the current leader, `false` otherwise.
+
+|===
+
+[discrete]
+===== Enabling confgiurations only when on leadership
+
+In order to leverage leaderelection provider and enable
+specific inputs only when Agent holds the leadership lock, users
+can use conditions based on `kubernetes_leaderelection.leader` key.
+Below we provide an example that will enable `state_container`
+metricset only when the leadership lock is acquired:
+
+[source,yaml]
+----
+- data_stream:
+    dataset: kubernetes.state_container
+    type: metrics
+  metricsets:
+    - state_container
+  add_metadata: true
+  hosts:
+    - 'kube-state-metrics:8080'
+  period: 10s
+  condition: ${kubernetes_leaderelection.leader} == true
+----
+
 [discrete]
 [[dynamic-providers]]
 === Dynamic Providers