Overview

The Kube Cluster Receiver automatically collects a core set of Kubernetes cluster metrics.

In addition to the default metrics, you can enable additional cluster metrics to collect more detailed status and troubleshooting information from your Kubernetes environment.

Additional metrics can help you identify:

• Why a pod is in a specific state
• Why a container was terminated or is waiting
• Current node conditions and health status
• Other cluster-level operational issues

These metrics are disabled by default and can be enabled through the k8s_cluster configuration in the OpsRamp Agent infrastructure metrics ConfigMap.

When enabled, additional metrics are collected alongside the existing cluster metrics without requiring an agent upgrade or image rebuild.

Before you begin

Ensure that:

• You have permission to view and edit ConfigMaps in the namespace where the OpsRamp Agent is installed.
• You know the namespace where the OpsRamp Agent is installed. The examples in this document use opsramp-agent.
• The k8s_cluster collector is enabled. For information about configuring the collector, see Kube Cluster Receiver.

Configuration location

Configure additional cluster metrics in the infrastructure metrics ConfigMap installed by the OpsRamp Agent.

To view the current ConfigMap, run:

kubectl get configmap opsramp-k8s-infra-metric-user-config -n opsramp-agent -o yaml

Example:

k8s_cluster:
  enabled: true
  config:
    scrape_interval: "2m"
  metrics:
    <metric-name>:
      enabled: true

Inside receivers.yaml, each collector (for example apiserver, kubelet_stats, k8s_cluster) is a top-level block. Optional metrics are configured under the k8s_cluster block:

Enable additional cluster metrics

To enable additional metrics, follow these steps:

Step 1: Open the ConfigMap

kubectl edit configmap opsramp-k8s-infra-metric-user-config -n opsramp-agent

Step 2: Locate the k8s_cluster block

In the receivers.yaml value, locate the k8s_cluster: block.

Step 3: Add the metrics block

Add a metrics: section directly under k8s_cluster.

Correct configuration:

k8s_cluster:
  enabled: true
  config:
    scrape_interval: "2m"
  metrics:
    k8s.container.status.reason:
      enabled: true

Incorrect configuration:

k8s_cluster:
  enabled: true
  config:
    scrape_interval: "2m"
    metrics:
      k8s.container.status.reason:
        enabled: true

Step 4: Enable the required metrics

Under metrics:, add each metric that you want to collect and set it to enabled: true.

Example: enable single metrics

k8s_cluster:
  enabled: true
  config:
    scrape_interval: "2m"
  metrics:
    k8s.container.status.reason:
      enabled: true

Example: enable multiple metrics

k8s_cluster:
  enabled: true
  config:
    scrape_interval: "2m"
  metrics:
    k8s.container.status.reason:
      enabled: true
    k8s.node.condition:
      enabled: true
    k8s.pod.status_reason:
      enabled: true

Step 5: Save the configuration

Save and close the editor. Kubernetes automatically updates the ConfigMap with your changes.

Step 6: Allow the OpsRamp Agent to apply the change

The OpsRamp Agent automatically detects the ConfigMap update and regenerates the collector configuration. Configuration changes are typically applied within a few seconds.

Verify the configuration

Complete the following checks to verify that the additional metrics were applied successfully.

1. Identify the master OpsRamp Agent pod

The k8s_cluster metrics are generated by the master OpsRamp Agent pod. List the OpsRamp Agent pods:

kubectl get pods -n opsramp-agent

From the output, identify the master OpsRamp Agent pod.

2. View the generated collector configuration

Replace <master-pod> with the master OpsRamp Agent pod, and run:

kubectl exec -n opsramp-agent <master-pod> -- cat /opt/opsramp/agent/tmp/otel/infra/k8scluster-receiver.yaml

3. Verify the enabled metrics

Confirm that the metrics you enabled appear in the generated configuration.

Example:

metrics:
  k8s.container.status.reason:
    enabled: true
  k8s.node.condition:
    enabled: true
  k8s.pod.status_reason:
    enabled: true

Verify that:

• All configured metrics are present.
• Required metrics are set to enabled: true.
• No configuration errors exist.

4. Check Agent logs

kubectl logs -n opsramp-agent <master-pod> | grep -iE "Failed to start OTEL|error executing while creating template|Skipping invalid k8s_cluster metric"

If no matching entries are returned, no known configuration errors were detected.

Supported additional metrics

The following metrics can be enabled through the k8s_cluster.metrics configuration.

Metric format

Metrics can be defined using either the full format or shorthand format.

Full format

metrics:
  k8s.container.status.reason:
    enabled: true

Set enabled to false to disable the named metric entry:

metrics:
  k8s.container.status.reason:
    enabled: false

Shorthand format

metrics:
  k8s.container.status.reason: true

The shorthand format is equivalent to setting enabled: true in the full format.

metrics:
  k8s.container.status.reason:
    enabled: true

After enabling additional cluster metrics, verify that the metrics appear in your monitoring dashboards and are available for alerting, troubleshooting, and capacity analysis.