K8sattributes Processor

Available in: contrib, k8s Maintainers: @dmitryax, @fatsheep9146, @TylerHelmuth, @ChrsMark, @odubajDT Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

The processor automatically discovers k8s resources (pods), extracts metadata from them and adds the extracted metadata to the relevant spans, metrics and logs as resource attributes. The processor uses the kubernetes API to discover all pods running in a cluster, keeps a record of their IP addresses, pod UIDs and interesting metadata. The rules for associating the data passing through the processor (spans, metrics and logs) with specific Pod Metadata are configured via “pod_association” key. It represents a list of associations that are executed in the specified order until the first one is able to do the match.

Configuration

The processor stores the list of running pods and the associated metadata. When it sees a datapoint (log, trace or metric), it will try to associate the datapoint to the pod from where the datapoint originated, so we can add the relevant pod metadata to the datapoint. By default, it associates the incoming connection IP to the Pod IP. But for cases where this approach doesn’t work (sending through a proxy, etc.), a custom association rule can be specified. Each association is specified as a list of sources of associations. The maximum number of sources within an association is 4. A source is a rule that matches metadata from the datapoint to pod metadata. In order to get an association applied, all the sources specified need to match. Each sources rule is specified as a pair of from (representing the rule type) and name (representing the attribute name if from is set to resource_attribute). The following rule types are available:

connection: Takes the IP attribute from connection context (if available). In this case the processor must appear before any batching or tail sampling, which remove this information.
resource_attribute: Allows specifying the attribute name to lookup in the list of attributes of the received Resource. Semantic convention should be used for naming.

Example for a pod association configuration:

pod_association:
  # below association takes a look at the datapoint's k8s.pod.ip resource attribute and tries to match it with
  # the pod having the same attribute.
  - sources:
      - from: resource_attribute
        name: k8s.pod.ip
  # below association matches for pair `k8s.pod.name` and `k8s.namespace.name`
  - sources:
      - from: resource_attribute
        name: k8s.pod.name
      - from: resource_attribute
        name: k8s.namespace.name

If Pod association rules are not configured, resources are associated with metadata only by connection’s IP Address. Which metadata to collect is determined by metadata configuration that defines list of resource attributes to be added. Items in the list called exactly the same as the resource attributes that will be added. The following attributes are added by default:

k8s.namespace.name
k8s.pod.name
k8s.pod.uid
k8s.pod.start_time
k8s.deployment.name (derived from the ReplicaSet name by default. Set the deprecated deployment_name_from_replicaset option to false to use the ReplicaSet informer for deployment name lookup.)
k8s.node.name

These attributes are also available for the use within association rules by default. The metadata section can also be extended with additional attributes which, if present in the metadata section, are then also available for the use within association rules. Available attributes are:

k8s.namespace.name
k8s.pod.name
k8s.pod.hostname
k8s.pod.ip
k8s.pod.start_time
k8s.pod.uid
k8s.replicaset.uid
k8s.replicaset.name
k8s.deployment.uid
k8s.deployment.name
k8s.daemonset.uid
k8s.daemonset.name
k8s.statefulset.uid
k8s.statefulset.name
k8s.cronjob.uid
k8s.cronjob.name (by default uses a Job-name heuristic when only the name is needed; the Job informer is used when k8s.cronjob.uid is enabled and/or labels or annotations are extracted with from: job)
k8s.job.uid
k8s.job.name
k8s.node.name
k8s.node.uid
k8s.cluster.uid
service.namespace
service.name
service.version(cannot be used for source rules in the pod_association when it’s calculated based on container’s image tag/digest)
service.instance.id(cannot be used for source rules in the pod_association)
Any tags extracted from the pod labels and annotations, as described in extracting attributes from pod labels and annotations

Not all the attributes are guaranteed to be added. Only attribute names from metadata should be used for pod_association’s resource_attribute, because empty or non-existing values will be ignored. Additional container level attributes can be extracted. If a pod contains more than one container, either the container.id, or the k8s.container.name attribute must be provided in the incoming resource attributes to correctly associate the matching container to the resource:

If the container.id resource attribute is provided, the following additional attributes will be available:
- k8s.container.name
- container.image.name
- container.image.tag
- container.image.repo_digests (if k8s CRI populates repository digest field)
- service.version
- service.instance.id
If the k8s.container.name resource attribute is provided, the following additional attributes will be available:
- container.id (if the k8s.container.restart_count resource attribute is not provided, it’s not guaranteed to get the right container ID.)
- container.image.name
- container.image.tag
- container.image.repo_digests (if k8s CRI populates repository digest field)
- service.version
- service.instance.id
If the k8s.container.restart_count resource attribute is provided, it can be used to associate with a particular container instance. If it’s not set, the latest container instance will be used:
- container.id (not added by default, has to be specified in metadata)

Please note, however, that only container.id attribute can be used for source rules in the pod_association. To use container.id in pod association, at least one container attribute must be included in the metadata extraction configuration (e.g., container.id, container.image.name, etc.). Example for extracting container level attributes:

pod_association:
- sources:
    - from: connection
extract:
  metadata:
  - k8s.pod.name
  - k8s.pod.uid
  - container.image.name
  - container.image.tag
  - k8s.container.name

The previous configuration attaches the attributes listed in the metadata section to all resources received by a matching pod with the k8s.container.name attribute being present. For example, when the following trace

{
  "name": "lets-go",
  "context": {
    "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2",
    "span_id": "0x051581bf3cb55c13"
  },
  "parent_id": null,
  "start_time": "2022-04-29T18:52:58.114201Z",
  "end_time": "2022-04-29T18:52:58.114687Z",
  "attributes": {
    "k8s.container.name": "telemetrygen"
  }
}

is sent to the collector by the following pod,

apiVersion: v1
kind: Pod
metadata:
  annotations:
    workload: deployment
  name: telemetrygen-pod
  namespace: e2ek8senrichment
  uid: 038e2267-b473-489b-b48c-46bafdb852eb
spec:
  containers:
  - command:
    - /telemetrygen
    - traces
    - --otlp-insecure
    - --otlp-endpoint=otelcollector.svc.cluster.local:4317
    - --duration=10s
    - --rate=1
    - --otlp-attributes=k8s.container.name="telemetrygen"
    image: ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:0.112.0@sha256:b248ef911f93ae27cbbc85056d1ffacc87fd941bbdc2ffd951b6df8df72b8096
    name: telemetrygen
status:
  podIP: 10.244.0.11

the processor associates the received trace to the pod, based on the connection IP, and add those attributes to the resulting span:

{
  "name": "lets-go",
  "context": {
    "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2",
    "span_id": "0x051581bf3cb55c13"
  },
  "parent_id": null,
  "start_time": "2022-04-29T18:52:58.114201Z",
  "end_time": "2022-04-29T18:52:58.114687Z",
  "attributes": {
    "k8s.container.name": "telemetrygen",
    "k8s.pod.name": "telemetrygen-pod",
    "k8s.pod.uid": "038e2267-b473-489b-b48c-46bafdb852eb",
    "container.image.name": "telemetrygen",
    "container.image.tag": "0.112.0",
    "container.image.repo_digests": ["ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen@sha256:b248ef911f93ae27cbbc85056d1ffacc87fd941bbdc2ffd951b6df8df72b8096"]
  }
}

By default, the processor will be ready as soon as it starts, even if no metadata has been fetched yet. If data is sent to this processor before the metadata is synced, there will be no metadata to enrich the data with. To wait for the metadata to be synced before the processor is ready, set the wait_for_metadata option to true. Then the processor will not be ready until the metadata is fully synced. As a result, the start-up of the Collector will be blocked. If the metadata cannot be synced, the Collector will ultimately fail to start. If a timeout is reached, the processor will fail to start and return an error, which will cause the collector to exit. The timeout defaults to 10s and can be configured with the wait_for_metadata_timeout option. example for setting the processor to wait for metadata to be synced before it is ready:

wait_for_metadata: true
wait_for_metadata_timeout: 10s

Informer Cache Resync Period

Reprocessing the informer cache periodically (resyncing) enqueues all cached K8s objects back into event handlers. In large clusters (e.g., 100K pods), this causes significant CPU spikes, memory churn, and garbage collection overhead. Because resource state modifications are already pushed immediately via Kubernetes watch events, a resync period is almost entirely unnecessary.

watch_sync_period (default: 5m): The resync period for K8s informers. You may set this to 0s to disable resyncing completely (recommended for large clusters).

Pod Deletion Grace Period

After receiving a pod deletion event, the processor can keep the pod’s metadata in its lookup cache for a short period before eviction. This grace window ensures that delayed spans, metrics, or logs that belong to the deleted pod can still be correctly enriched.

pod_delete_grace_period (default: 120s): The grace period to wait before deleting a pod’s metadata from the lookup cache after a deletion event.

Extracting attributes from pod labels and annotations

The k8sattributesprocessor can also set resource attributes from k8s labels and annotations of pods, namespaces, deployments, statefulsets, daemonsets, jobs and nodes. The config for associating the data passing through the processor (spans, metrics and logs) with specific Pod/Namespace/Deployment/StatefulSet/DaemonSet/Job/Node annotations/labels is configured via “annotations” and “labels” keys. This config represents a list of annotations/labels that are extracted from pods/namespaces/deployments/statefulsets/daemonsets/jobs/nodes and added to spans, metrics and logs. Each item is specified as a config of tag_name (representing the tag name to tag the spans with), key (representing the key used to extract value) and from (representing the kubernetes object used to extract the value). The “from” field has the following possible values: “pod”, “namespace”, “deployment”, “statefulset”, “daemonset”, “job” and “node” and defaults to “pod” if none is specified. By default, extracting metadata from Deployments, StatefulSets, DaemonSets and Jobs is disabled. Enabling extraction of these metadata comes with an extra memory consumption cost. A few examples to use this config are as follows:

extract:
  annotations:
    - tag_name: a1 # extracts value of annotation from pods with key `annotation-one` and inserts it as a tag with key `a1`
      key: annotation-one
      from: pod
    - tag_name: a2 # extracts value of annotation from namespaces with key `annotation-two` and inserts it as a tag with key `a2`
      key: annotation-two
      from: namespace
    - tag_name: a3 # extracts value of annotation from nodes with key `annotation-three` and inserts it as a tag with key `a3`
      key: annotation-three
      from: node
  labels:
    - tag_name: l1 # extracts value of label from namespaces with key `label1` and inserts it as a tag with key `l1`
      key: label1
      from: namespace
    - tag_name: l2 # extracts value of label from pods with key `label2` and inserts it as a tag with key `l2`
      key: label2
      from: pod
    - tag_name: l3 # extracts value of label from nodes with key `label3` and inserts it as a tag with key `l3`
      key: label3
      from: node

Configuring recommended resource attributes

The processor can be configured to set the recommended resource attributes:

otel_annotations will translate resource.opentelemetry.io/foo to the foo resource attribute, etc.
deployment_name_from_replicaset is deprecated and will be removed in future releases. Deployment names are derived from ReplicaSet names by default by trimming the pod-template-hash suffix. Set this option to false only to force ReplicaSet informer lookup for deployment names. If k8s.deployment.uid is included in the extract metadata section, or deployment labels or annotations are being extracted (i.e. any extract.labels or extract.annotations rule with from: deployment), then the Deployment/ReplicaSet informers are started and this setting is ignored. Important: You must still include k8s.deployment.name (or service.name) in the extract.metadata section for the deployment name to be extracted. The processor derives the deployment name from the ReplicaSet’s naming convention without requiring direct access to Deployment resources, but the extraction rules must be enabled. Take the following ownerReference of a pod managed by deployment for example:

  ownerReferences:
  - apiVersion: apps/v1
    blockOwnerDeletion: true
    controller: true
    kind: ReplicaSet
    name: opentelemetry-collector-6c45f8d6f6
    uid: ee75293d-14ec-42a0-9548-a768d9e07c48

The Extracted deployment name is: opentelemetry-collector. Note: When deployment names are derived from ReplicaSet names, in rare cases where deployment names are between 247 and 253 characters, Kubernetes may truncate the name in the ReplicaSet to fit the pod template hash suffix within the DNS subdomain limit (253 chars), causing the extracted k8s.deployment.name to be slightly truncated. If this affects your workloads, you can set deployment_name_from_replicaset: false or enable the k8s.deployment.uid attribute for accurate retrieval from the Kubernetes API, but at an extra cost in memory. Also note that for CronJob names (k8s.cronjob.name) a similar pattern applies, but it uses the Job informer (not ReplicaSet) and there is no deployment_name_from_replicaset-style flag. With only k8s.cronjob.name in extract.metadata, the processor derives the CronJob name from the Job’s name using a heuristic (8-digit time suffix aligned with pod creation time) and does not start a Job informer. The Job informer is started when k8s.cronjob.uid is enabled, or when labels or annotations are extracted with from: job, in which case the CronJob name can be resolved from the API when available. That reduces RBAC needs and memory use when you only need the CronJob name (no jobs watch for that attribute alone). Example:

  extract:
    otel_annotations: true
    metadata:
      - service.namespace
      - service.name
      - service.version
      - service.instance.id

Config example

k8s_attributes:
  auth_type: "serviceAccount"
  passthrough: false
  filter:
    # only retrieve pods running on the same node as the collector
    node_from_env_var: KUBE_NODE_NAME
  extract:
    # The attributes provided in 'metadata' will be added to associated resources
    metadata:
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.deployment.name  # Derived from the ReplicaSet name by default.
      - k8s.namespace.name
      - k8s.node.name
      - k8s.pod.start_time
      - service.namespace
      - service.name
      - service.version
      - service.instance.id
    labels:
      # This label extraction rule takes the value 'app.kubernetes.io/component' label and maps it to the 'app.label.component' attribute which will be added to the associated resources
      - tag_name: app.label.component
        key: app.kubernetes.io/component
        from: pod
    otel_annotations: true
  pod_association:
    - sources:
        # This rule associates all resources containing the 'k8s.pod.ip' attribute with the matching pods. If this attribute is not present in the resource, this rule will not be able to find the matching pod.
        - from: resource_attribute
          name: k8s.pod.ip
    - sources:
        # This rule associates all resources containing the 'k8s.pod.uid' attribute with the matching pods. If this attribute is not present in the resource, this rule will not be able to find the matching pod.
        - from: resource_attribute
          name: k8s.pod.uid
    - sources:
        # This rule will use the IP from the incoming connection from which the resource is received, and find the matching pod, based on the 'pod.status.podIP' of the observed pods
        - from: connection

Common Use Cases

Example 1: Basic Agent Deployment (DaemonSet)

Minimal configuration for an agent collecting telemetry from pods on the same node:

processors:
  k8s_attributes:
    # Use downward API to automatically filter by current node
    filter:
      node_from_env_var: KUBE_NODE_NAME
    # Extract common metadata
    extract:
      metadata:
        - k8s.namespace.name
        - k8s.pod.name
        - k8s.pod.uid
        - k8s.deployment.name
        - k8s.node.name
    # Default connection-based pod association
    pod_association:
      - sources:
          - from: connection

Required environment variable in your collector DaemonSet:

env:
  - name: KUBE_NODE_NAME
    valueFrom:
      fieldRef:
        fieldPath: spec.nodeName

Example 2: Gateway Deployment with Resource Attribute Association

Gateway configuration that receives telemetry from agents that have already added pod IP:

processors:
  k8s_attributes:
    # Extract comprehensive metadata
    extract:
      metadata:
        - k8s.namespace.name
        - k8s.pod.name
        - k8s.pod.uid
        - k8s.deployment.name
        - k8s.statefulset.name
        - k8s.daemonset.name
        - k8s.node.name
      # Extract custom labels
      labels:
        - tag_name: deployment_mode
          key: deployment_mode
          from: pod
        - tag_name: owner_team
          key: team
          from: pod
    # Associate by resource attributes set by agents
    pod_association:
      - sources:
          - from: resource_attribute
            name: k8s.pod.ip

Example 3: Production Deployment with Namespace Filtering

Configuration for monitoring a specific namespace with comprehensive metadata:

processors:
  k8s_attributes:
    filter:
      namespace: production
    extract:
      metadata:
        - k8s.namespace.name
        - k8s.pod.name
        - k8s.pod.uid
        - k8s.deployment.name
        - k8s.node.name
        - service.name
        - service.version
      labels:
        - tag_name: team
          key: team
          from: namespace
        - tag_name: environment
          key: environment
          from: pod
      annotations:
        - tag_name: commit_sha
          key: git-commit
          from: pod
      otel_annotations: true

Example 4: Memory-Optimized Configuration

Minimal memory footprint configuration for large clusters:

processors:
  k8s_attributes:
    filter:
      node_from_env_var: KUBE_NODE_NAME
    extract:
      # Only extract essential fields
      metadata:
        - k8s.namespace.name
        - k8s.pod.name
        - k8s.pod.uid
        # Deployment names are derived from ReplicaSet names by default, but
        # k8s.deployment.name must still be listed to enable extraction.
        - k8s.deployment.name

Example 5: Multi-Container Pod Support

Configuration for extracting container-level metadata:

processors:
  k8s_attributes:
    filter:
      node_from_env_var: KUBE_NODE_NAME
    extract:
      metadata:
        - k8s.namespace.name
        - k8s.pod.name
        - k8s.pod.uid
        - k8s.container.name
        - container.id
        - container.image.name
        - container.image.tag
    # Associate by container ID for multi-container pods
    pod_association:
      - sources:
          - from: resource_attribute
            name: container.id
      - sources:
          - from: connection

Role-based access control

Cluster-scoped RBAC

If you’d like to set up the k8sattributesprocessor to receive telemetry from across namespaces, it will need get, watch and list permissions on both pods and namespaces resources, for all namespaces and pods included in the configured filters. Additionally, when using k8s.deployment.uid, when using k8s.deployment.name with the deprecated deployment_name_from_replicaset: false, or when extracting labels or annotations with from: deployment, the processor needs get, watch and list permissions for replicasets resources. When using k8s.node.uid or extracting metadata from node, the processor needs get, watch and list permissions for nodes resources. With only k8s.cronjob.name (and no k8s.cronjob.uid, and no label or annotation extraction with from: job), the processor does not need get, watch and list permissions for jobs resources. When using k8s.cronjob.uid, or when extracting labels or annotations with from: job, the processor also needs get, watch and list permissions for jobs resources. Here is an example of a ClusterRole to give a ServiceAccount the necessary permissions for all pods, nodes, and namespaces in the cluster (replace <OTEL_COL_NAMESPACE> with a namespace where collector is deployed):

apiVersion: v1
kind: ServiceAccount
metadata:
  name: collector
  namespace: <OTEL_COL_NAMESPACE>
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: otel-collector
rules:
- apiGroups: [""]
  resources: ["pods", "namespaces", "nodes"]
  verbs: ["get", "watch", "list"]
- apiGroups: ["apps"]
  resources: ["replicasets", "deployments", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
  resources: ["jobs"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["extensions"]
  resources: ["replicasets"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: otel-collector
subjects:
- kind: ServiceAccount
  name: collector
  namespace: <OTEL_COL_NAMESPACE>
roleRef:
  kind: ClusterRole
  name: otel-collector
  apiGroup: rbac.authorization.k8s.io

Namespace-scoped RBAC

When running the k8sattributesprocessor to receive telemetry traffic from pods in a specific namespace, you can use a k8s Role and Rolebinding to provide collector access to query pods and replicasets in the namespace. This would require setting the filter::namespace config as shown below.

k8s_attributes:
  filter:
    namespace: <WORKLOAD_NAMESPACE>

With the namespace filter set, the processor will only look up pods and replicasets (when ReplicaSet lookup is needed, such as deployment_name_from_replicaset: false, k8s.deployment.uid, or deployment label/annotation extraction) in the selected namespace. Note that with just a role binding, the processor cannot query metadata such as labels and annotations from k8s nodes and namespaces which are cluster-scoped objects. This also means that the processor cannot set the value for k8s.cluster.uid attribute if enabled, since the k8s.cluster.uid attribute is set to the uid of the namespace kube-system which is not queryable with namespaced rbac. Please note, when extracting the workload related attributes, these workloads need to be present in the Role with the correct permissions. For example, an extraction of k8s.deployment.label.* attributes, deployments need to be present in Role. Example Role and RoleBinding to create in the namespace being watched.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: otel-collector
  namespace: <OTEL_COL_NAMESPACE>
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: otel-collector
  namespace: <WORKLOAD_NAMESPACE>
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "watch", "list"]
- apiGroups: ["apps"]
  resources: ["replicasets", "deployments", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
  resources: ["jobs"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: otel-collector
  namespace: <WORKLOAD_NAMESPACE>
subjects:
- kind: ServiceAccount
  name: otel-collector
  namespace: <OTEL_COL_NAMESPACE>
roleRef:
  kind: Role
  name: otel-collector
  apiGroup: rbac.authorization.k8s.io

Deployment scenarios

The processor can be used in collectors deployed both as an agent (Kubernetes DaemonSet) or as a gateway (Kubernetes Deployment).

As an agent

When running as an agent, the processor detects IP addresses of pods sending spans, metrics or logs to the agent and uses this information to extract metadata from pods. When running as an agent, it is important to apply a discovery filter so that the processor only discovers pods from the same host that it is running on. Not using such a filter can result in unnecessary resource usage especially on very large clusters. Once the filter is applied, each processor will only query the k8s API for pods running on its own node. Node filter can be applied by setting the filter.node config option to the name of a k8s node. While this works as expected, it cannot be used to automatically filter pods by the same node that the processor is running on in most cases as it is not know before hand which node a pod will be scheduled on. Luckily, kubernetes has a solution for this called the downward API. To automatically filter pods by the node the processor is running on, you’ll need to complete the following steps:

Use the downward API to inject the node name as an environment variable. Add the following snippet under the pod env section of the OpenTelemetry container.

spec:
  containers:
  - env:
    - name: KUBE_NODE_NAME
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: spec.nodeName

This will inject a new environment variable to the OpenTelemetry container with the value as the name of the node the pod was scheduled to run on.

Set “filter.node_from_env_var” to the name of the environment variable holding the node name.

k8s_attributes:
  filter:
    node_from_env_var: KUBE_NODE_NAME # this should be same as the var name used in previous step

This will restrict each OpenTelemetry agent to query pods running on the same node only dramatically reducing resource requirements for very large clusters.

As a gateway

When running as a gateway, the processor cannot correctly detect the IP address of the pods generating the telemetry data without any of the well-known IP attributes, when it receives them from an agent instead of receiving them directly from the pods. To workaround this issue, agents deployed with the k8s_attributes processor can be configured to detect the IP addresses and forward them along with the telemetry data resources. Collector can then match this IP address with k8s pods and enrich the records with the metadata. In order to set this up, you’ll need to complete the following steps:

Setup agents in passthrough mode Configure the agents’ k8s_attributes processors to run in passthrough mode.

k8s_attributes:
  passthrough: true

This will ensure that the agents detect the IP address as add it as an attribute to all telemetry resources. Agents will not make any k8s API calls, do any discovery of pods or extract any metadata.

Configure the collector as usual No special configuration changes are needed to be made on the collector. It’ll automatically detect the IP address of spans, logs and metrics sent by the agents as well as directly by other services/pods.

Complete Configuration Options

Below is a comprehensive configuration example with all available options:

k8s_attributes:
  # Authentication type for Kubernetes API access
  # Options: "none", "serviceAccount", "kubeConfig"
  # Default: "serviceAccount"
  auth_type: "serviceAccount"
  
  # Kubernetes API server context (only used when auth_type is "kubeConfig")
  # Default: ""
  context: ""
  
  # Maximum number of queries per second to the Kubernetes API
  # Uses client-go's default if unset. Increase if you see client-side throttling warnings.
  # Default: 5
  kube_api_qps: 5
  
  # Maximum burst of requests to the Kubernetes API
  # Uses client-go's default if unset. Increase if you see client-side throttling warnings.
  # Default: 10
  kube_api_burst: 10
  
  # Passthrough mode - only annotates resources with pod IP without extracting metadata
  # Useful for agents that don't need K8s API access
  # Default: false
  passthrough: false
  
  # Wait for metadata to be synced before marking processor as ready
  # When true, collector startup will block until metadata is available
  # Default: false
  wait_for_metadata: false
  
  # Maximum time to wait for metadata sync during startup
  # Only applies when wait_for_metadata is true
  # Default: 10s
  wait_for_metadata_timeout: 10s
  
  # Informer resync period. Setting this to 0s disables resyncing completely.
  # Default: 5m
  watch_sync_period: 5m
  
  # Grace period to wait before removing deleted pods from the cache.
  # Default: 120s
  pod_delete_grace_period: 120s
  
  # Extract configuration - defines what metadata to extract
  extract:
    # Metadata fields to extract as resource attributes
    # Default: [k8s.namespace.name, k8s.pod.name, k8s.pod.uid, k8s.pod.start_time, k8s.deployment.name, k8s.node.name]
    # Full description of each metadata attribute can be found in the semantic conventions:
    # https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource/k8s
    metadata:
      - k8s.namespace.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.hostname
      - k8s.pod.start_time
      - k8s.pod.ip
      - k8s.deployment.name
      - k8s.deployment.uid
      - k8s.replicaset.name
      - k8s.replicaset.uid
      - k8s.daemonset.name
      - k8s.daemonset.uid
      - k8s.statefulset.name
      - k8s.statefulset.uid
      - k8s.job.name
      - k8s.job.uid
      - k8s.cronjob.name
      - k8s.cronjob.uid
      - k8s.node.name
      - k8s.node.uid
      - k8s.cluster.uid
      - k8s.container.name
      - container.id
      - container.image.name
      - container.image.tag
      - container.image.repo_digests
      # See [the configuration section](#configuration) for more details
      - service.namespace
      - service.name
      - service.version
      - service.instance.id
    
    # Extract pod annotations as resource attributes
    # See [Extracting attributes from pod labels and annotations](#extracting-attributes-from-pod-labels-and-annotations) section for more details
    annotations:
      - tag_name: annotation_value  # Resource attribute name
        key: my-annotation           # Annotation key to extract
        from: pod                     # Source: pod, namespace, deployment, statefulset, daemonset, job, or node
      - tag_name: deployment_annotation
        key: app.version
        from: deployment
      # Extract multiple annotations matching a regex pattern
      - tag_name: $1                 # Use regex capture group
        key_regex: custom\.(.*)      # Extract all annotations matching pattern
        from: pod
      # Extract all annotations (use with caution - may extract many attributes)
      - tag_name: $$1
        key_regex: (.*)
        from: pod
    
    # Extract pod labels as resource attributes
    # See [Extracting attributes from pod labels and annotations](#extracting-attributes-from-pod-labels-and-annotations) section for more details
    labels:
      - tag_name: label_value        # Resource attribute name
        key: my-label                # Label key to extract
        from: pod                     # Source: pod, namespace, deployment, statefulset, daemonset, job, or node
      - tag_name: namespace_label
        key: environment
        from: namespace
      # Extract multiple labels matching a regex pattern
      - tag_name: $1                 # Use regex capture group
        key_regex: app\.(.*)         # Extract all labels matching pattern
        from: pod
      # Extract labels matching a pattern without specifying tag_name
      # Uses default format: k8s.pod.labels.<label_key>
      - key_regex: environment\.(.*)  # Extract labels starting with "environment."
        from: pod
      # Extract all labels (use with caution - may extract many attributes)
      - tag_name: $$1
        key_regex: (.*)
        from: pod
    
    # Extract OpenTelemetry resource attributes from pod annotations
    # See [Configuring recommended resource attributes](#configuring-recommended-resource-attributes) section for more details
    # Annotations with prefix "resource.opentelemetry.io/" become resource attributes
    # Example: "resource.opentelemetry.io/service.version" → "service.version"
    # Default: false
    otel_annotations: true
    
    # Deprecated. Deployment names are derived from ReplicaSet names by default.
    # Set to false only to force ReplicaSet informer lookup.
    # See [Configuring recommended resource attributes](#configuring-recommended-resource-attributes) section for more details
    # Default: true
    deployment_name_from_replicaset: true
  
  # Filter configuration - restrict which pods to monitor
  filter:
    # Filter by node name (static)
    node: "node-1"
    
    # Filter by node name from environment variable (dynamic)
    # Use with Kubernetes downward API to automatically filter by current node
    node_from_env_var: "KUBE_NODE_NAME"
    
    # Filter by namespace
    namespace: "my-namespace"
    
    # Filter by field selectors
    fields:
      - key: spec.nodeName
        value: "node-1"
        op: equals              # Options: equals, not-equals
      - key: status.phase
        value: "Running"
        op: equals
    
    # Filter by label selectors
    labels:
      - key: app
        value: "my-app"
        op: equals              # Options: equals, not-equals, exists, does-not-exist
      - key: environment
        value: "production"
        op: equals
      - key: monitoring
        op: exists
  
  # Pod association rules - define how to match telemetry data to pods
  # Rules are evaluated in order; first match wins
  # Note: If a source attribute is found but doesn't match any pod, the association fails
  # and subsequent rules will not be evaluated
  # Maximum 4 sources per rule
  pod_association:
    # Rule 1: Match by pod IP from resource attribute
    - sources:
        - from: resource_attribute
          name: k8s.pod.ip
    
    # Rule 2: Match by pod UID from resource attribute
    - sources:
        - from: resource_attribute
          name: k8s.pod.uid
    
    # Rule 3: Match by pod name AND namespace (both must match)
    - sources:
        - from: resource_attribute
          name: k8s.pod.name
        - from: resource_attribute
          name: k8s.namespace.name
    
    # Rule 4: Match by connection IP (default if no rules specified)
    - sources:
        - from: connection
  
  # Exclude configuration - ignore specific pods
  exclude:
    pods:
      - name: "jaeger-agent"        # Exact pod name to exclude
      - name: "jaeger-collector"

Configuration Options Reference

Top-Level Options

Option	Type	Default	Description
`auth_type`	string	`serviceAccount`	Authentication method for K8s API: `none`, `serviceAccount`, or `kubeConfig`
`context`	string	`""`	K8s context to use (only when `auth_type: kubeConfig`)
`kube_api_qps`	float32	`5`	Max queries per second to K8s API. Increase if you see client-side throttling warnings
`kube_api_burst`	int	`10`	Max burst of requests to K8s API. Increase if you see client-side throttling warnings
`passthrough`	bool	`false`	Only add pod IP without extracting metadata (no K8s API calls)
`wait_for_metadata`	bool	`false`	Block collector startup until metadata is synced
`wait_for_metadata_timeout`	duration	`10s`	Max wait time for metadata sync on startup
`watch_sync_period`	duration	`5m`	Resync period for K8s informers (`0s` disables resync completely)
`pod_delete_grace_period`	duration	`120s`	Grace period to wait before deleting pod metadata from the cache on deletion

Extract Options

Option	Type	Default	Description
`metadata`	[]string	See below	List of metadata fields to extract as resource attributes
`annotations`	[]FieldExtractConfig	`[]`	Pod/namespace/node annotations to extract
`labels`	[]FieldExtractConfig	`[]`	Pod/namespace/node labels to extract
`otel_annotations`	bool	`false`	Extract OpenTelemetry resource attributes from pod annotations with prefix `resource.opentelemetry.io/`
`deployment_name_from_replicaset`	bool	`true`	Deprecated; will be removed in future releases. When `true`, ReplicaSet informer is not run for deployment names only, relying on a heuristic instead.

Default metadata fields:

k8s.namespace.name
k8s.pod.name
k8s.pod.uid
k8s.pod.start_time
k8s.deployment.name
k8s.node.name

Available metadata fields: All fields listed in the “Complete Configuration Options” section above under extract.metadata.

FieldExtractConfig Options

Option	Type	Default	Description
`tag_name`	string	Auto-generated	Resource attribute name (supports regex backreferences with `key_regex`)
`key`	string	`""`	Exact annotation/label key to extract (mutually exclusive with `key_regex`)
`key_regex`	string	`""`	Regex pattern to match annotation/label keys (mutually exclusive with `key`)
`from`	string	`pod`	Source to extract from: `pod`, `namespace`, `deployment`, `statefulset`, `daemonset`, `job`, or `node`

Option	Type	Default	Description
`node`	string	`""`	Filter pods by specific node name
`node_from_env_var`	string	`""`	Environment variable containing node name to filter by
`namespace`	string	`""`	Filter pods by specific namespace
`fields`	[]FieldFilterConfig	`[]`	Filter by K8s field selectors
`labels`	[]FieldFilterConfig	`[]`	Filter by K8s label selectors

FieldFilterConfig Options

Option	Type	Default	Description
`key`	string	Required	Field or label key
`value`	string	`""`	Field or label value
`op`	string	`equals`	Operation: `equals`, `not-equals` (fields); `equals`, `not-equals`, `exists`, `does-not-exist` (labels)

PodAssociationConfig Options

Option	Type	Default	Description
`sources`	[]AssociationSource	Required	List of sources to match (maximum 4, all must match)

AssociationSource Options

Option	Type	Default	Description
`from`	string	Required	Source type: `connection` or `resource_attribute`
`name`	string	Conditional	Resource attribute name (required when `from: resource_attribute`)

Exclude Options

Option	Type	Default	Description
`pods`	[]ExcludePodConfig	Default excludes	List of pods to exclude from processing

ExcludePodConfig Options

Option	Type	Default	Description
`name`	string	Required	Pod name pattern (regex) to exclude

Default excluded pods:

jaeger-agent
jaeger-collector

Caveats

There are some edge-cases and scenarios where k8s_attributes will not work properly.

Host networking mode

The processor cannot correct identify pods running in the host network mode and enriching telemetry data generated by such pods is not supported at the moment, unless the association rule is not based on IP attribute.

As a sidecar

The processor does not support detecting containers from the same pods when running as a sidecar. While this can be done, we think it is simpler to just use the kubernetes downward API to inject environment variables into the pods and directly use their values as tags.

Compatibility

Kubernetes Versions

This processor is tested against the Kubernetes versions specified in the e2e-tests.yml workflow. These tested versions represent the officially supported Kubernetes versions for this component.

Production Deployment Guide

Scaling Considerations

Memory Consumption

The processor maintains an in-memory cache of K8s metadata for all pods it monitors. Memory usage scales with:

Number of pods monitored: Each pod’s metadata (labels, annotations, owner references) is cached
Metadata fields extracted: More fields = more memory per pod
Label/annotation extraction rules: Regex patterns and multiple rules increase overhead
Workload metadata: Extracting deployment/statefulset/daemonset/job metadata adds additional caching

Memory estimates:

Agent mode (node-filtered): ~50-200 MB for 100 pods per node
Gateway mode (cluster-wide): ~500 MB - 2 GB for 1000-10000 pods
With workload metadata: Add 20-30% overhead

Optimization strategies:

Use node filtering in agent deployments: filter.node_from_env_var: KUBE_NODE_NAME
Limit metadata extraction: Only extract fields you need
Rely on the default deployment-name heuristic: Reduces memory by not caching replicaset data
Filter by namespace: Limits scope when monitoring specific applications
Avoid extracting workload metadata unless necessary (deployment, statefulset, etc.)

CPU Usage

CPU usage is generally low but increases with:

High telemetry throughput: Each data point requires pod lookup and attribute enrichment
Frequent pod churn: More K8s API watch events to process
Complex association rules: Multiple rules with many sources

Recommended resource limits:

Agent mode: 100-500m CPU, 256-512 Mi memory
Gateway mode: 500m-2 CPU, 1-4 Gi memory

High Availability

For gateway deployments, run multiple replicas with:

Load balancer distributing telemetry traffic
Each replica independently queries K8s API and maintains its own cache
No shared state between replicas
Horizontal scaling based on CPU/memory usage

For production deployments using Helm charts, see the official OpenTelemetry Kube Stack chart and the isolated multicollector deployment example.

# Example: 3 replicas for HA
replicas: 3
resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: 2
    memory: 4Gi

Graceful Shutdown

The processor is stateless and requires no special shutdown procedures:

Collector receives SIGTERM
Processor stops watching K8s API
In-flight telemetry data is processed
Collector shuts down cleanly

No persistent storage required - all metadata is refreshed from K8s API on startup.

Timestamp Format

By default, the k8s.pod.start_time uses Time.MarshalText() to format the timestamp value as an RFC3339 compliant timestamp.

Self-Observability Features

The processor exposes internal telemetry metrics for monitoring its operation. For a complete list of all available metrics, see the Internal Telemetry documentation. Key metrics to monitor:

otelcol_otelsvc_k8s_ip_lookup_miss: Number of times pod lookup by IP failed
- High values indicate association issues
otelcol_otelsvc_k8s_pod_added / otelcol_otelsvc_k8s_pod_deleted: Track pod churn rates
- Monitor for unexpected spikes in pod lifecycle events
otelcol_otelsvc_k8s_pod_table_size: Current size of pod metadata cache
- Use to monitor memory consumption trends

Warnings

Memory consumption: Since the processor fetches and caches the K8s metadata for the resources of the node it is on, it consumes more memory than other processors. That consumption is compounded if users don’t filter down to only the metadata for the node the processor is running on.

Feature Gates

See documentation.md for the complete list of feature gates supported by this processor. Feature gates can be enabled using the --feature-gates flag:

"--feature-gates=<feature-gate>"

Semantic Conventions Compatibility

The processor is moving towards the latest Semantic Conventions through the following feature gates:

processor.k8sattributes.DontEmitV0K8sConventions
processor.k8sattributes.EmitV1K8sConventions

This follows the migration pattern described by the respective Collector RFC. The breaking changes between the 2 schemas are the following:

container.image.tag -> container.image.tags
k8s.pod.labels.<key> -> k8s.pod.label.<key>
k8s.pod.annotations.<key> -> k8s.pod.annotation.<key>
k8s.node.labels.<key> -> k8s.node.label.<key>
k8s.node.annotations.<key> -> k8s.node.annotation.<key>
k8s.namespace.labels.<key> -> k8s.namespace.label.<key>
k8s.namespace.annotations.<key> -> k8s.namespace.annotation.<key>

All attributes emitted through the processor.k8sattributes.EmitV1K8sConventions feature gate are currently in release_candidate stability and are actively moving towards stable stability.

Available Benchmarks

The component is tested as part of the project’s load tests, with the results being publicly available at the benchmarks page. In that page, users can find details such as memory and CPU performance when the component is used in K8s Clusters (tests use KWOK) with a range number of workloads. Refer to the test for more information about the setup.

Attributes

Attribute Name	Description	Type	Values
`otelcol.signal`	The signal type the telemetry metric is associated with	string	`metrics`, `traces`, `logs`, `profiles`
`pod_identifier`	The source(s) used to identify the pod, formatted as ‘from/name’ (e.g., ‘connection’, ‘resource_attribute/k8s.pod.ip’). Does not contain actual identifier values to avoid high cardinality.	string
`status`	The status of the pod association operation	string	`success`, `error`

Resource Attributes

Attribute Name	Description	Type	Enabled
`container.id`	Container ID. Usually a UUID, as for example used to identify Docker containers. The UUID might be abbreviated. Requires k8s.container.restart_count.	string	❌
`container.image.name`	Name of the image the container was built on. Requires container.id or k8s.container.name.	string	✅
`container.image.repo_digests`	Repo digests of the container image as provided by the container runtime.	slice	❌
`container.image.tag`	Container image tag. Defaults to “latest” if not provided (unless digest also in image path) Requires container.id or k8s.container.name. Deprecated, use container.image.tags instead.	string	✅
`container.image.tags`	Container image tags. Defaults to “latest” if not provided (unless digest also in image path). Requires container.id or k8s.container.name.	slice	✅
`k8s.cluster.uid`	Gives cluster uid identified with kube-system namespace	string	❌
`k8s.container.name`	The name of the Container in a Pod template. Requires container.id.	string	❌
`k8s.cronjob.name`	The name of the CronJob.	string	❌
`k8s.cronjob.uid`	The uid of the CronJob.	string	❌
`k8s.daemonset.name`	The name of the DaemonSet.	string	❌
`k8s.daemonset.uid`	The UID of the DaemonSet.	string	❌
`k8s.deployment.name`	The name of the Deployment.	string	✅
`k8s.deployment.uid`	The UID of the Deployment.	string	❌
`k8s.job.name`	The name of the Job.	string	❌
`k8s.job.uid`	The UID of the Job.	string	❌
`k8s.namespace.name`	The name of the namespace that the pod is running in.	string	✅
`k8s.node.name`	The name of the Node.	string	✅
`k8s.node.uid`	The UID of the Node.	string	❌
`k8s.pod.hostname`	The hostname of the Pod.	string	❌
`k8s.pod.ip`	The IP address of the Pod.	string	❌
`k8s.pod.name`	The name of the Pod.	string	✅
`k8s.pod.start_time`	The start time of the Pod.	string	✅
`k8s.pod.uid`	The UID of the Pod.	string	✅
`k8s.replicaset.name`	The name of the ReplicaSet.	string	❌
`k8s.replicaset.uid`	The UID of the ReplicaSet.	string	❌
`k8s.statefulset.name`	The name of the StatefulSet.	string	❌
`k8s.statefulset.uid`	The UID of the StatefulSet.	string	❌
`service.instance.id`	The instance ID of the service.	string	❌
`service.name`	The name of the service.	string	❌
`service.namespace`	The namespace of the service.	string	❌
`service.version`	The version of the service.	string	❌

Configuration

Example Configuration

k8s_attributes:
k8s_attributes/2:
  passthrough: false
  auth_type: "kubeConfig"
  extract:
    metadata:
      # the following metadata fields configuration options are deprecated
      # - podName
      # - podUID
      # - deployment
      # - namespace
      # - node
      # - startTime
      # extract the following well-known metadata fields from pods and namespaces
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.ip
      - k8s.deployment.name
      - k8s.namespace.name
      - k8s.node.name
      - k8s.pod.start_time
      - k8s.cluster.uid

    annotations:
      - tag_name: a1 # extracts value of annotation with key `annotation-one` and inserts it as a tag with key `a1`
        key: annotation-one
        from: pod
      - tag_name: a2 # extracts value of annotation with key `annotation-two` with regexp and inserts it as a tag with key `a2`
        key: annotation-two
        from: pod
    labels:
      - tag_name: l1 # extracts value of label with key `label1` and inserts it as a tag with key `l1`
        key: label1
        from: pod
      - tag_name: l2 # extracts value of label with key `label1` with regexp and inserts it as a tag with key `l2`
        key: label2
        from: pod

  filter:
    namespace: ns2 # only look for pods running in ns2 namespace
    node: ip-111.us-west-2.compute.internal # only look for pods running on this node/host
    node_from_env_var: K8S_NODE # only look for pods running on the node/host specified by the K8S_NODE environment variable
    labels: # only consider pods that match the following labels
      - key: key1 # match pods that have a label `key1=value1`. `op` defaults to "equals" when not specified
        value: value1
      - key: key2 # ignore pods that have a label `key2=value2`.
        value: value2
        op: not-equals
    fields: # works the same way as labels but for fields instead (like annotations)
      - key: key1
        value: value1
      - key: key2
        value: value2
        op: not-equals

  pod_association:
    - sources:
      - from: resource_attribute
        name: ip
    - sources:
      - from: resource_attribute
        name: k8s.pod.ip
    - sources:
      - from: resource_attribute
        name: host.name
    - sources:
      - from: connection
        name: ip

  exclude:
    pods:
      - name: jaeger-agent
      - name: jaeger-collector

k8s_attributes/3:
  passthrough: false
  auth_type: "kubeConfig"
  extract:
    annotations:
      - key_regex: opentel.* # extracts Keys & values of annotations matching regex `opentel.*`
        from: pod
    labels:
      - key_regex: opentel.* # extracts Keys & values of labels matching regex `opentel.*`
        from: pod

k8s_attributes/4:
  auth_type: "kubeConfig"
  extract:
    metadata:
      # the following metadata field has been deprecated
      - k8s.cluster.name

k8s_attributes/too_many_sources:
  pod_association:
    - sources:
        - from: resource_attribute
          name: custom-attribute
        - from: resource_attribute
          name: ip
        - from: resource_attribute
          name: k8s.pod.ip
        - from: resource_attribute
          name: host.name
        - from: connection
          name: ip

k8s_attributes/bad_keys_labels:
  extract:
    labels:
      - tag_name: l1
        key: label1
        key_regex: label\d

k8s_attributes/bad_keys_annotations:
  extract:
    annotations:
      - tag_name: a1
        key: annotation1
        key_regex: annotation\d

k8s_attributes/bad_from_labels:
  extract:
    labels:
      - tag_name: a1
        key: label1
        from: unknown

k8s_attributes/bad_from_annotations:
  extract:
    annotations:
      - tag_name: a1
        key: annotation1
        from: unknown

k8s_attributes/bad_keyregex_labels:
  extract:
    labels:
      - tag_name: a1
        from: pod
        key_regex: "["

k8s_attributes/bad_keyregex_annotations:
  extract:
    annotations:
      - tag_name: a1
        from: pod
        key_regex: "["

k8s_attributes/bad_filter_label_op:
  filter:
    labels:
      - key: label
        value: v1
        op: "unknown"

k8s_attributes/deployment_name_from_replicaset:
  extract:
    deployment_name_from_replicaset: true
k8s_attributes/deployment_name_from_replicaset_false:
  extract:
    deployment_name_from_replicaset: false
k8s_attributes/bad_filter_field_op:
  filter:
    fields:
      - key: field
        value: v1
        op: "exists"

k8s_attributes/otel_annotations:
  extract:
    otel_annotations: true

k8s_attributes/wait_for_metadata:
  wait_for_metadata: true
  wait_for_metadata_timeout: 30s

k8s_attributes/passthrough_mode:
  passthrough: true

k8s_attributes/filter_label_exists:
  filter:
    labels:
      - key: app
        op: exists

k8s_attributes/filter_label_does_not_exist:
  filter:
    labels:
      - key: deprecated-label
        op: does-not-exist

k8s_attributes/extract_from_namespace:
  extract:
    labels:
      - tag_name: ns_label
        key: team
        from: namespace
    annotations:
      - tag_name: ns_annotation
        key: owner
        from: namespace

k8s_attributes/extract_from_node:
  extract:
    labels:
      - tag_name: node_label
        key: node-role
        from: node
    metadata:
      - k8s.node.name
      - k8s.node.uid

k8s_attributes/extract_from_deployment:
  extract:
    labels:
      - tag_name: deployment_label
        key: app
        from: deployment

k8s_attributes/extract_from_statefulset:
  extract:
    labels:
      - tag_name: statefulset_label
        key: app
        from: statefulset

k8s_attributes/extract_from_daemonset:
  extract:
    labels:
      - tag_name: daemonset_label
        key: app
        from: daemonset

k8s_attributes/extract_from_job:
  extract:
    labels:
      - tag_name: job_label
        key: app
        from: job

k8s_attributes/all_metadata_fields:
  extract:
    metadata:
      - k8s.namespace.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.hostname
      - k8s.pod.start_time
      - k8s.pod.ip
      - k8s.deployment.name
      - k8s.deployment.uid
      - k8s.replicaset.name
      - k8s.replicaset.uid
      - k8s.daemonset.name
      - k8s.daemonset.uid
      - k8s.statefulset.name
      - k8s.statefulset.uid
      - k8s.job.name
      - k8s.job.uid
      - k8s.cronjob.name
      - k8s.cronjob.uid
      - k8s.node.name
      - k8s.node.uid
      - k8s.container.name
      - container.id
      - container.image.name
      - container.image.tag
      - container.image.repo_digests
      - service.namespace
      - service.name
      - service.version
      - service.instance.id
      - k8s.cluster.uid

k8s_attributes/both_container_image_tags:
  extract:
    metadata:
      - container.image.tag
      - container.image.tags

k8s_attributes/bad_metadata_field:
  extract:
    metadata:
      - invalid.metadata.field

k8s_attributes/custom_intervals:
  watch_sync_period: 20s
  pod_delete_grace_period: 30s

k8s_attributes/bad_watch_sync_period:
  watch_sync_period: -20s

k8s_attributes/disable_watch_sync:
  watch_sync_period: 0s

k8s_attributes/bad_pod_delete_grace_period:
  pod_delete_grace_period: -30s

Last generated: 2026-06-01

​K8sattributes Processor

​Supported Telemetry

​Overview

​Configuration

​Informer Cache Resync Period

​Pod Deletion Grace Period

​Extracting attributes from pod labels and annotations

​Configuring recommended resource attributes

​Config example

​Common Use Cases

​Example 1: Basic Agent Deployment (DaemonSet)

​Example 2: Gateway Deployment with Resource Attribute Association

​Example 3: Production Deployment with Namespace Filtering

​Example 4: Memory-Optimized Configuration

​Example 5: Multi-Container Pod Support

​Role-based access control

​Cluster-scoped RBAC

​Namespace-scoped RBAC

​Deployment scenarios

​As an agent

​As a gateway

​Complete Configuration Options

​Configuration Options Reference

​Top-Level Options

​Extract Options

​FieldExtractConfig Options

​Filter Options

​FieldFilterConfig Options

​PodAssociationConfig Options

​AssociationSource Options

​Exclude Options

​ExcludePodConfig Options

​Caveats

​Host networking mode

​As a sidecar

​Compatibility

​Kubernetes Versions

​Production Deployment Guide

​Scaling Considerations

​Memory Consumption

​CPU Usage

​High Availability

​Graceful Shutdown

​Timestamp Format

​Self-Observability Features

​Warnings

​Feature Gates

​Semantic Conventions Compatibility

​Available Benchmarks

​Attributes

​Resource Attributes

​Configuration

​Example Configuration

K8sattributes Processor

Supported Telemetry

Overview

Configuration

Informer Cache Resync Period

Pod Deletion Grace Period

Extracting attributes from pod labels and annotations

Configuring recommended resource attributes

Config example

Common Use Cases

Example 1: Basic Agent Deployment (DaemonSet)

Example 2: Gateway Deployment with Resource Attribute Association

Example 3: Production Deployment with Namespace Filtering

Example 4: Memory-Optimized Configuration

Example 5: Multi-Container Pod Support

Role-based access control

Cluster-scoped RBAC

Namespace-scoped RBAC

Deployment scenarios

As an agent

As a gateway

Complete Configuration Options

Configuration Options Reference

Top-Level Options

Extract Options

FieldExtractConfig Options

Filter Options

FieldFilterConfig Options

PodAssociationConfig Options

AssociationSource Options

Exclude Options

ExcludePodConfig Options

Caveats

Host networking mode

As a sidecar

Compatibility

Kubernetes Versions

Production Deployment Guide

Scaling Considerations

Memory Consumption

CPU Usage

High Availability

Graceful Shutdown

Timestamp Format

Self-Observability Features

Warnings

Feature Gates

Semantic Conventions Compatibility

Available Benchmarks

Attributes

Resource Attributes

Configuration

Example Configuration