K8s Attributes Processor

Overview

The Kubernetes Attributes Processor enriches telemetry data (logs, metrics, and traces) with Kubernetes metadata by querying the Kubernetes API.

Supported types: Logs · Metrics · Traces

Note: This processor is designed to run in Kubernetes environments. Support depends on Kubernetes deployment rather than the host OS.

Authentication

Parameter	Type	Description
auth_type	string	Authentication method for accessing Kubernetes API. Supported values include serviceAccount (default, for in-cluster usage) and kubeConfig (for external access).

Metadata Extraction

Parameter	Type	Default Value	Required	Description
extract.metadata	array	predefined set	No	List of Kubernetes metadata fields to extract (e.g., k8s.pod.name, k8s.namespace.name, k8s.node.name, etc.).
extract.otel_annotations	boolean	false	No	Extract pod annotations with prefix resource.opentelemetry.io/ as resource attributes.
extract.deployment_name_from_replicaset	boolean	false	No	Derives deployment name from replicaset by removing pod template hash suffix.

Labels

Defines how Kubernetes labels are extracted and mapped to telemetry attributes.

Parameter	Type	Default Value	Required	Description
key	string	none	Conditional	Exact label key to extract.
key_regex	string	none	Conditional	Regex pattern to match multiple label keys.
tag_name	string	none	No	Rename the extracted label to a custom attribute name.
from	string	pod	No	Source resource for labels (pod, namespace, node, deployment, statefulset, daemonset, job).

Annotations

Defines how Kubernetes Annotations are extracted and mapped to telemetry attributes.

Parameter	Type	Default Value	Required	Description
key	string	none	Conditional	Exact Annotation key to extract.
key_regex	string	none	Conditional	Regex pattern to match multiple Annotation keys.
tag_name	string	none	No	Rename the extracted Annotation to a custom attribute name.
from	string	pod	No	Source resource for labels (pod, namespace, node, deployment, statefulset, daemonset, job).

Filter Configuration

Parameter	Type	Default Value	Required	Description
namespace	string	none	No	Only process telemetry from pods in this namespace.
node	string	none	No	Only process telemetry from pods running on this node.
node_from_env_var	string	none	No	Reads node name from environment variable (commonly K8S_NODE_NAME).
fields	array	[]	No	Filter pods using Kubernetes field selectors.
labels	array	[]	No	Filter pods using label selectors.

Pod Association

Defines how incoming telemetry is matched to Kubernetes pods.

Parameter	Type	Default Value	Required	Description
sources	array	none	Yes	Ordered list of sources used to associate telemetry with a pod.

Common association sources:

• resource_attribute (e.g., k8s.pod.ip, k8s.pod.uid)
• connection (uses client IP)

Exclude Configuration

Parameter	Type	Default Value	Required	Description
exclude.pods	array	[]	No	List of pod names to exclude from processing.

Metadata Sync

Parameter	Type	Default Value	Required	Description
wait_for_metadata	boolean	false	No	Wait until Kubernetes metadata is fully synced before processing telemetry.
wait_for_metadata_timeout	string	1m	No	Maximum duration to wait for metadata synchronization.

Advanced Settings

Parameter	Type	Default Value	Required	Description
passthrough	boolean	false	No	If enabled, skips metadata enrichment and passes data through unchanged.

Example Configuration

{
  "auth_type": "serviceAccount", // default: "serviceAccount"

  "extract": {
    "metadata": ["k8s.pod.name", "k8s.namespace.name", "k8s.node.name"],
    "otel_annotations": false,
    "deployment_name_from_replicaset": true,
  },

  "filter": {
    "namespace": "production",
  },

  "pod_association": [
    {
      "sources": [
        {
          "from": "resource_attribute",
          "name": "k8s.pod.ip",
        },
        {
          "from": "connection",
        },
      ],
    },
  ],

  "exclude": {
    "pods": ["test-pod"],
  },

  "wait_for_metadata": false,
  "wait_for_metadata_timeout": "1m",

  "passthrough": false,
}