[DOCS] Kubernetes Cluster receiver (k8s_cluster)

docs/reference/edot-collector/components/k8sclusterreceiver.md

@@ -0,0 +1,204 @@
+---
+navigation_title: Kubernetes Cluster receiver
+description: Collects Kubernetes cluster-level metrics and entity events for Elastic Observability through the EDOT Collector.
+applies_to:
+  stack:
+  serverless:
+    observability:
+  product:
+    edot_collector:
+products:
+  - id: cloud-serverless
+  - id: observability
+  - id: edot-collector
+---
+
+# Kubernetes Cluster receiver
+
+The Kubernetes Cluster receiver (`k8s_cluster`) is a core component of the {{edot}} (EDOT) Collector. It collects cluster-level metrics and entity events from the Kubernetes API server, enabling observability into node health, resource allocation, and workload states in Elastic Observability.
+
+This receiver should be deployed as a single instance per cluster. It uses the Kubernetes API to watch for updates and emit metrics and events to your configured exporters.
+
+For full contrib details, see the [OpenTelemetry k8s_cluster receiver documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/k8sclusterreceiver).
+
+
+## Get started
+
+To use the Kubernetes Cluster receiver, include it in the `receivers` section of your EDOT Collector configuration. The receiver is already bundled in the default EDOT Collector distribution.
+
+```yaml
+receivers:
+  k8s_cluster:
+    auth_type: serviceAccount
+```
+
+You can then reference it in your service pipelines to collect cluster-level metrics and entity events:
+
+```yaml
+service:
+  pipelines:
+    metrics:
+      receivers: [k8s_cluster]
+      exporters: [elasticsearch]
+```
+
+
+## How it works
+
+The receiver authenticates to the Kubernetes API (using a service account, kubeconfig, or no authentication) and continuously watches cluster objects such as Pods, Nodes, Deployments, and StatefulSets.
+
+It produces three kinds of data:
+
+- **Metrics** — cluster-wide and namespace-scoped performance data  
+- **Logs** — entity change events, when attached to a logs pipeline  
+- **Metadata updates** — sent to exporters that implement metadata sync interfaces
+
+The receiver can coordinate multiple instances using the `k8s_leader_elector` extension, ensuring only one active collector scrapes data at any given time.
+
+
+
+## Configuration
+
+Example minimal configuration:
+
+```yaml
+receivers:
+  k8s_cluster:
+    auth_type: serviceAccount
+    collection_interval: 10s
+    metadata_collection_interval: 5m
+    node_conditions_to_report: [Ready]
+    allocatable_types_to_report: [cpu, memory]
+
+exporters:
+  elasticsearch:
+    endpoints: [${ELASTIC_ENDPOINT}]
+    api_key: ${ELASTIC_API_KEY}
+
+service:
+  pipelines:
+    metrics:
+      receivers: [k8s_cluster]
+      exporters: [elasticsearch]
+    logs/entity_events:
+      receivers: [k8s_cluster]
+      exporters: [elasticsearch]
+```
+
+
+
+### Key settings
+
+The following configuration options control how the receiver connects to the Kubernetes API and emits metrics.
+
+| Setting | Description | Default |
+|----------|--------------|----------|
+| `auth_type` | Authentication method used. (`none`, `serviceAccount`, or `kubeConfig`). | `serviceAccount` |
+| `collection_interval` | How frequently metrics are emitted. | `10s` |
+| `metadata_collection_interval` | How often cluster metadata is refreshed. Set to `0` to turn off. | `5m` |
+| `node_conditions_to_report` | List of node conditions to report (for example `Ready`, `MemoryPressure`). | `[Ready]` |
+| `allocatable_types_to_report` | Resource types to report (`cpu`, `memory`, `ephemeral-storage`, `pods`). When empty, no allocatable metrics are emitted. | `[]` (unless explicitly configured) |
+| `distribution` | Kubernetes distribution used. (`kubernetes` or `openshift`). | `kubernetes` |
+| `namespaces` | Limit observation to specific namespaces. Cluster-level objects (like Nodes) won’t be collected. | none |
+
+For the full configuration schema, refer to [contrib config.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/k8sclusterreceiver/config.go).
+
+
+
+## Metrics overview
+
+The `k8s_cluster` receiver emits a comprehensive set of metrics describing the state and resource usage of cluster entities.
+
+Some key metric categories include:
+
+| Metric prefix | Description | Example |
+|----------------|--------------|----------|
+| `k8s.node.*` | Node-level conditions, allocatable resources, and status. | `k8s.node.condition_ready`, `k8s.node.allocatable_cpu` |
+| `k8s.pod.*` | Pod lifecycle and phase metrics. | `k8s.pod.phase`, `k8s.pod.status_reason` |
+| `k8s.container.*` | Container resource requests/limits and restart counts. | `k8s.container.cpu_limit`, `k8s.container.restarts` |
+| `k8s.deployment.*`, `k8s.daemonset.*`, `k8s.statefulset.*` | Workload availability and replica metrics. | `k8s.deployment.desired`, `k8s.daemonset.ready_nodes` |
+| `k8s.resource_quota.*` | Namespace quota usage and limits. | `k8s.resource_quota.used` |
+| `openshift.*` | OpenShift-specific cluster quota metrics. | `openshift.clusterquota.limit` |
+
+Each metric can be turned on or off individually:
+
+```yaml
+metrics:
+  k8s.container.cpu_limit:
+    enabled: false
+```
+
+For a full reference list of default and optional metrics, refer to the [contrib documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/k8sclusterreceiver/documentation.md).
+
+
+
+## Resource attributes
+
+Telemetry emitted by this receiver includes rich metadata attributes that provide context about where and how the data was collected.
+
+The most common attributes include:
+
+| Attribute | Description | Example |
+|------------|--------------|----------|
+| `k8s.node.name` | Node name where the pod is scheduled | `gke-prod-node-01` |
+| `k8s.pod.name` | Pod name | `nginx-deployment-6c9c57f9d4-8z8xk` |
+| `k8s.namespace.name` | Namespace of the resource | `default` |
+| `k8s.container.name` | Container name | `nginx` |
+| `container.image.name` | Container image name | `nginx` |
+| `container.image.tag` | Container image tag | `1.27` |
+
+To turn off specific attributes:
+
+```yaml
+resource_attributes:
+  container.id:
+    enabled: false
+```
+
+
+
+## Use cases in Elastic Observability
+
+Typical use cases for this receiver in Elastic Observability include:
+
+- Cluster health monitoring - view node readiness, allocatable capacity, and workload distribution.  
+- Workload lifecycle tracking - track deployments, jobs, and cronjobs through phases and conditions.  
+- Resource quota enforcement - observe namespace or cluster-level resource quotas and usage trends.  
+- OpenShift observability - when `distribution: openshift` is set, collect OpenShift-specific quota metrics.
+
+Combine with the `k8sobjects` receiver for detailed resource inventory data.
+
+
+
+## RBAC permissions
+
+The receiver requires access to Kubernetes resources controlled by RBAC (Role-Based Access Control). When using `serviceAccount` authentication, assign a `ClusterRole` and `ClusterRoleBinding` that grant `get`, `list`, and `watch` permissions.
+
+If using the `namespaces` setting to scope access, create `Role` and `RoleBinding` resources per namespace.  
+
+:::{note}
+Creating `Role` and `RoleBinding` resources per namespace limits visibility into cluster-wide resources like Nodes and ClusterResourceQuotas.
+:::
+
+See [contrib RBAC examples](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/k8sclusterreceiver#rbac).
+
+
+
+## Caveats and limitations
+
+Be aware of the following considerations and limitations when deploying the `k8s_cluster` receiver:
+
+- Only one active `k8s_cluster` instance should run per cluster. Use `k8s_leader_elector` extension for high availability (HA).
+- Restricting namespaces turns off some cluster-level metrics.  
+- Contrib metric stability: development (logs) and beta (metrics).  
+- Requires direct access to the Kubernetes API and appropriate RBAC permissions.
+
+
+
+## See also
+
+- [Contrib `k8s_cluster` receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/k8sclusterreceiver)  
+- [Kubernetes environments](opentelemetry://reference/architecture/k8s.md)  
+<!--- [Kubernetes Objects receiver]()  
+
+ - [Filelog receiver]() --->

docs/reference/edot-collector/toc.yml

@@ -15,6 +15,7 @@ toc:
     children:
       - file: components/elasticsearchexporter.md
       - file: components/elasticapmintakereceiver.md
+      - file: components/k8sclusterreceiver.md
   - file: customization.md
     children:
       - file: custom-collector.md