> ## Documentation Index > Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt > Use this file to discover all available pages before exploring further. # Kubernetes > Kubernetes workload, node, cluster state, and control-plane metrics, and Kubernetes logs. The Kubernetes integration requires CXDOT Collector 1.4.0 or greater. [Kubernetes](https://kubernetes.io/) is an open source system for automating the deployment, scaling, and management of containerized applications. Use the Kubernetes integration with the Chronosphere XDOT Collector to collect workload, node, cluster state, and control-plane metrics and Kubernetes logs. The Kubernetes integration supports Kubernetes 1.31 or greater. The integration supports managed and self-managed distributions that implement the upstream Kubernetes APIs. Provider restrictions on control-plane endpoints and audit logs can limit the telemetry available from managed clusters. ## Supported telemetry types The Kubernetes integration supports these telemetry types: | Type | Supported | | ------- | --------- | | Logs | Yes | | Metrics | Yes | | Traces | No | | Events | No | The integration sends Kubernetes Events through the logs signal. ## Prerequisites The Kubernetes integration has the following prerequisites: * Grant the Collector service accounts the Kubernetes API permissions required by the enabled capabilities. The Helm chart creates the required roles and bindings, so the identity that installs the chart must be permitted to create them. * Make the Kubernetes API and the endpoints for each enabled Kubernetes component reachable from the Collector tier that collects them. Each node Collector connects directly to its node's kubelet on port `10250` for kubelet and cAdvisor metrics. * To collect control-plane metrics through pod discovery, schedule node collectors on control-plane nodes. These nodes commonly have taints that the node collectors must tolerate. * Audit log collection is supported only when the API server writes its audit log to `/var/log/kubernetes/audit.log`. Managed Kubernetes providers typically don't expose this file, and audit log webhook backends aren't supported. ## Configure To configure the Kubernetes integration, follow these steps: At the integration level, you can enable or disable collection, identify the cluster, and choose how the Collector authenticates to the Kubernetes API. The Kubernetes integration provides the following component configuration: | Component | Collects | Enabled by default | Configurable behavior | | -------------------- | ------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------- | | `kubelet` | Pod, container, node, and volume metrics from the kubelet stats API | Yes | Collection cadence, timeout, and metric selection | | `kubelet_metrics` | Kubelet lifecycle, runtime operation, API client, and Go runtime metrics | Yes | Collection cadence and timeout | | `cadvisor` | Per-container CPU, memory, and block I/O metrics from cAdvisor | Yes | Collection cadence, timeout, and sample timestamps | | `container_logs` | Pod standard output and standard error logs with pod and container metadata | No | Log collection | | `audit_logs` | Kubernetes API server audit records from control-plane nodes | No | Log collection | | `cluster` | Cluster resource state metrics and resource-change logs | Yes | Namespaces, collection cadence, timeout, metric selection, and Secret metadata collection | | `events` | Kubernetes Events from all namespaces as logs | Yes | Event collection | | `apiserver` | Kubernetes API server request, performance, and service-level indicator metrics | No | Collection cadence, timeout, and static targets | | `scheduler` | Kubernetes scheduler queue, scheduling, and service-level indicator metrics | Yes | Collection cadence, timeout, and static targets | | `controller_manager` | Kubernetes controller work queue, reconciliation, and service-level indicator metrics | Yes | Collection cadence, timeout, and static targets | | `kube_proxy` | kube-proxy network programming and request metrics | No | Collection cadence, timeout, and static targets | | `coredns` | CoreDNS request, response, cache, and process metrics | Yes | Collection cadence, timeout, and static targets | Custom kubelet and cluster metric selections replace their default metric selections. When you customize either set, restate every default metric that you want to retain. Enabling Secret metadata collection grants the cluster Collector permission to list and watch Secret objects across the cluster. For the complete list of fields, accepted values, and defaults, consult the configuration reference on this page. 1. Optional: Enable metrics from additional Kubernetes components. The Collector discovers supported component pods by their standard labels and ports. For example, add the following to the `values.yaml` for your Helm chart: ```yaml theme={null} config: integrations: kubernetes: apiserver: enabled: true kube_proxy: enabled: true ``` Metrics from discovered pods arrive with that pod's Kubernetes metadata attached. For more information, see [enrichment](https://docs.chronosphere.io/ingest/cxdot-collector/enrichment). 2. Optional: Add tolerations for tainted nodes whose node-local components you want to monitor. A node Collector must run on a control-plane node to collect its scheduler, controller manager, and audit log. For example, tolerate the standard control-plane taint: ```yaml theme={null} nodeCollector: tolerations: - key: node-role.kubernetes.io/control-plane operator: Exists effect: NoSchedule ``` 3. Optional: Configure static targets for Kubernetes components that pod discovery can't reach. Managed Kubernetes providers might not expose scheduler or controller manager metrics endpoints; the integration can't collect those metrics unless the provider exposes a reachable endpoint. For example, add the following to the `values.yaml` for your Helm chart: ```yaml theme={null} config: integrations: kubernetes: apiserver: enabled: true static_targets: - endpoint: kubernetes.default.svc:443 ``` Static targets supplement discovered component pods. One leader-elected replica collects static API server, scheduler, controller manager, and CoreDNS targets per cluster. Static kube-proxy targets run on the node tier. ### Validate To validate the Kubernetes integration, follow these steps: 1. In the Live Telemetry Analyzer, filter for `cxdot.integration.name=kubernetes`. Confirm that the Kubernetes metric names appear. 2. In Metrics Explorer, run the following query: ```text theme={null} avg by ("k8s.cluster.name", "k8s.node.name") ({"k8s.node.cpu.usage"}) ``` Confirm that the query returns the expected time series for each node. 3. Optional: If you enabled Kubernetes Events, in Logs Explorer, search for `"cxdot.integration.name":=kubernetes "k8s.event.reason":*`. Confirm that events from your cluster appear. For more information about diagnosing a failing integration, see [Troubleshooting](https://docs.chronosphere.io/ingest/cxdot-collector/troubleshooting). ## Configuration reference Configure one Kubernetes integration instance with the following settings. In Helm values, place these settings under `config.integrations.kubernetes`. In a Collector configuration file, place them under `cxdot.integrations.kubernetes`. ### Optional settings * **`enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`cluster_name`** Type: `string`. Optional. Cluster identifier injected as the `k8s.cluster.name` resource attribute on every signal. NB: deployments that set a global cluster identifier apply it last, overriding this one — the CXDOT Helm chart does, and rejects a `cluster_name` here that disagrees with its own value rather than letting the two diverge silently. * **`auth`** Type: `string`. Optional. Default: `serviceAccount`. How the integration authenticates to the K8s API. `serviceAccount` uses the in-cluster pod token; `kubeConfig` reads \$KUBECONFIG / \~/.kube/config (kubectl-style); `none` is unauthenticated. Allowed values: `serviceAccount`, `kubeConfig`, `none`. * **`kubelet`** Type: `object`. Optional. Settings for collecting node, pod, container, and volume metrics from each node's kubelet stats endpoint. * **`kubelet.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`kubelet.collection_interval`** Type: `duration`. Optional. Default: `20s`. How often the Collector collects metrics from each node's kubelet. * **`kubelet.timeout`** Type: `duration`. Optional. Default: `20s`. Maximum time the Collector waits for a kubelet stats response during one collection. * **`kubelet.metrics`** Type: `object`. Optional. Default: `{"k8s.container.cpu_limit_utilization":{"enabled":true},"k8s.container.memory_limit_utilization":{"enabled":true},"k8s.node.system_container.cpu.usage":{"enabled":true},"k8s.node.system_container.memory.usage":{"enabled":true},"k8s.pod.cpu_limit_utilization":{"enabled":true},"k8s.pod.cpu_request_utilization":{"enabled":true},"k8s.pod.memory_limit_utilization":{"enabled":true},"k8s.pod.memory_request_utilization":{"enabled":true}}`. Pass-through to the kubeletstats receiver's `metrics:` block — per-metric `enabled:` toggles for metrics that are off by default upstream, keyed by metric name. Validated against the receiver's own config schema. Setting this replaces the whole default map below rather than merging into it, so restate any default you still want. * **`kubelet_metrics`** Type: `object`. Optional. Settings for collecting the kubelet's own Prometheus metrics from each node. * **`kubelet_metrics.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`kubelet_metrics.collection_interval`** Type: `duration`. Optional. Default: `15s`. How often the Collector scrapes each node's kubelet metrics endpoint. * **`kubelet_metrics.timeout`** Type: `duration`. Optional. Default: `10s`. Maximum time the Collector waits for one scrape to complete. * **`cadvisor`** Type: `object`. Optional. Settings for collecting container resource metrics from each node's cAdvisor endpoint. * **`cadvisor.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`cadvisor.collection_interval`** Type: `duration`. Optional. Default: `15s`. How often the Collector scrapes each node's cAdvisor endpoint. * **`cadvisor.timeout`** Type: `duration`. Optional. Default: `10s`. Maximum time the Collector waits for one scrape to complete. * **`cadvisor.honor_timestamps`** Type: `boolean`. Optional. Default: `true`. Whether to keep the timestamps cAdvisor attaches to its samples, which date from its last internal housekeeping pass and can trail the scrape by tens of seconds. Set false to stamp samples at scrape time instead — for ingest paths whose sample-recency window is tight enough to reject samples that are already old when scraped. * **`container_logs`** Type: `object`. Optional. Settings for collecting container logs from each node. * **`container_logs.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`audit_logs`** Type: `object`. Optional. Settings for collecting Kubernetes API server audit logs. * **`audit_logs.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`cluster`** Type: `object`. Optional. Settings for collecting cluster-level object state — deployments, pods, nodes, and other resources — from the Kubernetes API. * **`cluster.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`cluster.namespaces`** Type: `array of string`. Optional. Restrict cluster resource collection to these namespaces. Omitted or empty collects every namespace. * **`cluster.collection_interval`** Type: `duration`. Optional. Default: `10s`. How often the Collector reads cluster object state. * **`cluster.timeout`** Type: `duration`. Optional. Default: `10s`. Maximum time the Collector waits for one read to complete. * **`cluster.allow_secrets_read`** Type: `boolean`. Optional. Default: `false`. Allow the cluster collector to read Secrets cluster-wide (list/watch), which kube-state-metrics requires to emit the Secret metadata metrics (`kubernetes_state.secret.count` and `.type`). Off by default: because Kubernetes LIST/WATCH return full Secret objects including `data`, the grant exposes every Secret's contents to the collector's ServiceAccount. Leave it off unless you need these metrics. * **`cluster.metrics`** Type: `object`. Optional. Default: `{"k8s.container.status.reason":{"enabled":true},"k8s.pod.status_reason":{"enabled":true},"k8s.service.endpoint.count":{"enabled":true}}`. Pass-through to the k8s\_cluster receiver's `metrics:` block — per-metric `enabled:` toggles for metrics that are off by default upstream, keyed by metric name. Validated against the receiver's own config schema. Setting this replaces the whole default map below rather than merging into it, so restate any default you still want. * **`events`** Type: `object`. Optional. Settings for collecting Kubernetes events as log records. * **`events.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`apiserver`** Type: `object`. Optional. Settings for scraping this Kubernetes control-plane component's metrics endpoint. * **`apiserver.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`apiserver.collection_interval`** Type: `duration`. Optional. Default: `30s`. How often the Collector scrapes the component's metrics endpoint. * **`apiserver.timeout`** Type: `duration`. Optional. Default: `10s`. Maximum time the Collector waits for one scrape to complete. * **`apiserver.static_targets`** Type: `array of object`. Optional. List of static fallback targets; non-empty list switches the static\_configs discovery source on alongside any k8s\_pod-discovered entities. Omitted or empty = pure k8s\_pod discovery only. * **`apiserver.static_targets[].endpoint`** Type: `string`. Required. `host:port` of the scrape target, for example, `127.0.0.1:6443`. * **`scheduler`** Type: `object`. Optional. Settings for scraping this Kubernetes control-plane component's metrics endpoint. * **`scheduler.collection_interval`** Type: `duration`. Optional. Default: `30s`. How often the Collector scrapes the component's metrics endpoint. * **`scheduler.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`scheduler.static_targets`** Type: `array of object`. Optional. List of static fallback targets; non-empty list switches the static\_configs discovery source on alongside any k8s\_pod-discovered entities. Omitted or empty = pure k8s\_pod discovery only. * **`scheduler.static_targets[].endpoint`** Type: `string`. Required. `host:port` of the scrape target, for example, `127.0.0.1:6443`. * **`scheduler.timeout`** Type: `duration`. Optional. Default: `10s`. Maximum time the Collector waits for one scrape to complete. * **`controller_manager`** Type: `object`. Optional. Settings for scraping this Kubernetes control-plane component's metrics endpoint. * **`controller_manager.collection_interval`** Type: `duration`. Optional. Default: `30s`. How often the Collector scrapes the component's metrics endpoint. * **`controller_manager.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`controller_manager.static_targets`** Type: `array of object`. Optional. List of static fallback targets; non-empty list switches the static\_configs discovery source on alongside any k8s\_pod-discovered entities. Omitted or empty = pure k8s\_pod discovery only. * **`controller_manager.static_targets[].endpoint`** Type: `string`. Required. `host:port` of the scrape target, for example, `127.0.0.1:6443`. * **`controller_manager.timeout`** Type: `duration`. Optional. Default: `10s`. Maximum time the Collector waits for one scrape to complete. * **`kube_proxy`** Type: `object`. Optional. Settings for scraping this Kubernetes control-plane component's metrics endpoint. * **`kube_proxy.collection_interval`** Type: `duration`. Optional. Default: `30s`. How often the Collector scrapes the component's metrics endpoint. * **`kube_proxy.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`kube_proxy.static_targets`** Type: `array of object`. Optional. List of static fallback targets; non-empty list switches the static\_configs discovery source on alongside any k8s\_pod-discovered entities. Omitted or empty = pure k8s\_pod discovery only. * **`kube_proxy.static_targets[].endpoint`** Type: `string`. Required. `host:port` of the scrape target, for example, `127.0.0.1:6443`. * **`kube_proxy.timeout`** Type: `duration`. Optional. Default: `10s`. Maximum time the Collector waits for one scrape to complete. * **`coredns`** Type: `object`. Optional. Settings for scraping this Kubernetes control-plane component's metrics endpoint. * **`coredns.collection_interval`** Type: `duration`. Optional. Default: `30s`. How often the Collector scrapes the component's metrics endpoint. * **`coredns.enabled`** Type: `boolean`. Optional. Default: `true`. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn't run it. * **`coredns.static_targets`** Type: `array of object`. Optional. List of static fallback targets; non-empty list switches the static\_configs discovery source on alongside any k8s\_pod-discovered entities. Omitted or empty = pure k8s\_pod discovery only. * **`coredns.static_targets[].endpoint`** Type: `string`. Required. `host:port` of the scrape target, for example, `127.0.0.1:6443`. * **`coredns.timeout`** Type: `duration`. Optional. Default: `10s`. Maximum time the Collector waits for one scrape to complete. ## Related topics - [Kubernetes deployment settings](/ingest/pipeline/v2/configure/kubernetes.md) - [Automated Kubernetes logging](/ingest/pipeline/v2/build/automated-logging.md) - [Kubernetes Events source plugin](/ingest/pipeline/plugins/source-plugins/kubernetes.md) - [Scrape configuration using Kubernetes](/ingest/metrics-traces/collector/discover/scrape-configuration.md) - [Install a Core Operator in a Kubernetes cluster](/ingest/pipeline/v2/install/install-operator/kubernetes-cluster.md)