Skip to main content

Kubernetes Cluster State

Plugin: go.d.plugin Module: k8s_state

Overview

This collector monitors Kubernetes Nodes, Pods and Containers.

This collector is supported on all platforms.

This collector only supports collecting metrics from a single instance of this integration.

Default Behavior

Auto-Detection

This integration doesn't support auto-detection.

Limits

The default configuration for this integration does not impose any limits on data collection.

Performance Impact

The default configuration for this integration is not expected to impose a significant performance impact on the system.

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Per node

These metrics refer to the Node.

Labels:

LabelDescription
k8s_cluster_idCluster ID. This is equal to the kube-system namespace UID.
k8s_cluster_nameCluster name. Cluster name discovery only works in GKE.
k8s_node_nameNode name.

Metrics:

MetricDimensionsUnit
k8s_state.node_allocatable_cpu_requests_utilizationrequests%
k8s_state.node_allocatable_cpu_requests_usedrequestsmillicpu
k8s_state.node_allocatable_cpu_limits_utilizationlimits%
k8s_state.node_allocatable_cpu_limits_usedlimitsmillicpu
k8s_state.node_allocatable_mem_requests_utilizationrequests%
k8s_state.node_allocatable_mem_requests_usedrequestsbytes
k8s_state.node_allocatable_mem_limits_utilizationlimits%
k8s_state.node_allocatable_mem_limits_usedlimitsbytes
k8s_state.node_allocatable_pods_utilizationallocated%
k8s_state.node_allocatable_pods_usageavailable, allocatedpods
k8s_state.node_conditiona dimension per conditionstatus
k8s_state.node_schedulabilityschedulable, unschedulablestate
k8s_state.node_pods_readinessready%
k8s_state.node_pods_readiness_stateready, unreadypods
k8s_state.node_pods_conditionpod_ready, pod_scheduled, pod_initialized, containers_readypods
k8s_state.node_pods_phaserunning, failed, succeeded, pendingpods
k8s_state.node_containerscontainers, init_containerscontainers
k8s_state.node_containers_staterunning, waiting, terminatedcontainers
k8s_state.node_init_containers_staterunning, waiting, terminatedcontainers
k8s_state.node_ageageseconds

Per pod

These metrics refer to the Pod.

Labels:

LabelDescription
k8s_cluster_idCluster ID. This is equal to the kube-system namespace UID.
k8s_cluster_nameCluster name. Cluster name discovery only works in GKE.
k8s_node_nameNode name.
k8s_namespaceNamespace.
k8s_controller_kindController kind (ReplicaSet, DaemonSet, StatefulSet, Job, etc.).
k8s_controller_nameController name.
k8s_pod_namePod name.
k8s_qos_classPod QOS class (burstable, guaranteed, besteffort).

Metrics:

MetricDimensionsUnit
k8s_state.pod_cpu_requests_usedrequestsmillicpu
k8s_state.pod_cpu_limits_usedlimitsmillicpu
k8s_state.pod_mem_requests_usedrequestsbytes
k8s_state.pod_mem_limits_usedlimitsbytes
k8s_state.pod_conditionpod_ready, pod_scheduled, pod_initialized, containers_readystate
k8s_state.pod_phaserunning, failed, succeeded, pendingstate
k8s_state.pod_ageageseconds
k8s_state.pod_containerscontainers, init_containerscontainers
k8s_state.pod_containers_staterunning, waiting, terminatedcontainers
k8s_state.pod_init_containers_staterunning, waiting, terminatedcontainers

Per container

These metrics refer to the Pod container.

Labels:

LabelDescription
k8s_cluster_idCluster ID. This is equal to the kube-system namespace UID.
k8s_cluster_nameCluster name. Cluster name discovery only works in GKE.
k8s_node_nameNode name.
k8s_namespaceNamespace.
k8s_controller_kindController kind (ReplicaSet, DaemonSet, StatefulSet, Job, etc.).
k8s_controller_nameController name.
k8s_pod_namePod name.
k8s_qos_classPod QOS class (burstable, guaranteed, besteffort).
k8s_container_nameContainer name.

Metrics:

MetricDimensionsUnit
k8s_state.pod_container_readiness_statereadystate
k8s_state.pod_container_restartsrestartsrestarts
k8s_state.pod_container_staterunning, waiting, terminatedstate
k8s_state.pod_container_waiting_state_reasona dimension per reasonstate
k8s_state.pod_container_terminated_state_reasona dimension per reasonstate

Alerts

There are no alerts configured by default for this integration.

Setup

Prerequisites

No action required.

Configuration

File

The configuration file name for this integration is go.d/k8s_state.conf.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/k8s_state.conf

Options

There are no configuration options.

Examples

There are no configuration examples.

Troubleshooting

Debug Mode

Important: Debug mode is not supported for data collection jobs created via the UI using the Dyncfg feature.

To troubleshoot issues with the k8s_state collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn't working.

  • Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that's not the case on your system, open netdata.conf and look for the plugins setting under [directories].

    cd /usr/libexec/netdata/plugins.d/
  • Switch to the netdata user.

    sudo -u netdata -s
  • Run the go.d.plugin to debug the collector:

    ./go.d.plugin -d -m k8s_state

Getting Logs

If you're encountering problems with the k8s_state collector, follow these steps to retrieve logs and identify potential issues:

  • Run the command specific to your system (systemd, non-systemd, or Docker container).
  • Examine the output for any warnings or error messages that might indicate issues. These messages should provide clues about the root cause of the problem.

System with systemd

Use the following command to view logs generated since the last Netdata service restart:

journalctl _SYSTEMD_INVOCATION_ID="$(systemctl show --value --property=InvocationID netdata)" --namespace=netdata --grep k8s_state

System without systemd

Locate the collector log file, typically at /var/log/netdata/collector.log, and use grep to filter for collector's name:

grep k8s_state /var/log/netdata/collector.log

Note: This method shows logs from all restarts. Focus on the latest entries for troubleshooting current issues.

Docker Container

If your Netdata runs in a Docker container named "netdata" (replace if different), use this command:

docker logs netdata 2>&1 | grep k8s_state

Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.