Skip to main content

​
K8sevents Receiver

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

​
Supported Telemetry

Logs

​
Overview

Currently this receiver supports authentication via service accounts only. See example for more information.

​
Configuration

The following settings are optional:
  • auth_type (default = serviceAccount): Determines how to authenticate to the K8s API server. This can be one of none (for no auth), serviceAccount (to use the standard service account token provided to the agent pod), or kubeConfig to use credentials from ~/.kube/config.
  • namespaces (default = all): An array of namespaces to collect events from. This receiver will continuously watch all the namespaces mentioned in the array for new events.
  • kube_api_qps (default = 5): Maximum number of queries per second to the Kubernetes API. Increase this if you see client-side throttling warnings in the collector logs.
  • kube_api_burst (default = 10): Maximum burst size for requests to the Kubernetes API. Increase this alongside kube_api_qps if you see client-side throttling warnings.
  • k8s_leader_elector (default: none): if specified, will enable Leader Election by using k8sleaderelector extension
Examples: 
  k8s_events:
    auth_type: kubeConfig
    k8s_leader_elector: k8s_leader_elector
    namespaces: [default, my_namespace]
The full list of settings exposed for this receiver are documented in config.go with detailed sample configurations in testdata/config.yaml.

​
Example

Here is an example deployment of the collector that sets up this receiver along with the OTLP Exporter. Follow the below sections to setup various Kubernetes resources required for the deployment.

​
Configuration

Create a ConfigMap with the config for otelcontribcol. Replace OTLP_ENDPOINT with valid value. 
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: otelcontribcol
  labels:
    app: otelcontribcol
data:
  config.yaml: |
    receivers:
      k8s_events:
        namespaces: [default, my_namespace]
    exporters:
      otlp_grpc:
        endpoint: <OTLP_ENDPOINT>
        tls:
          insecure: true

    service:
      pipelines:
        logs:
          receivers: [k8s_events]
          exporters: [otlp_grpc]
EOF

​
Service Account

Create a service account that the collector should use. 
<<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app: otelcontribcol
  name: otelcontribcol
EOF

​
RBAC

Use the below commands to create a ClusterRole with required permissions and a ClusterRoleBinding to grant the role to the service account created above. 
<<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: otelcontribcol
  labels:
    app: otelcontribcol
rules:
- apiGroups:
  - ""
  resources:
  - events
  - namespaces
  - namespaces/status
  - nodes
  - nodes/spec
  - pods
  - pods/status
  - replicationcontrollers
  - replicationcontrollers/status
  - resourcequotas
  - services
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - apps
  resources:
  - daemonsets
  - deployments
  - replicasets
  - statefulsets
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - extensions
  resources:
  - daemonsets
  - deployments
  - replicasets
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - batch
  resources:
  - jobs
  - cronjobs
  verbs:
  - get
  - list
  - watch
- apiGroups:
    - autoscaling
  resources:
    - horizontalpodautoscalers
  verbs:
    - get
    - list
    - watch
EOF

<<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: otelcontribcol
  labels:
    app: otelcontribcol
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: otelcontribcol
subjects:
- kind: ServiceAccount
  name: otelcontribcol
  namespace: default
EOF

​
Deployment

Create a Deployment to deploy the collector. 
<<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: otelcontribcol
  labels:
    app: otelcontribcol
spec:
  replicas: 1
  selector:
    matchLabels:
      app: otelcontribcol
  template:
    metadata:
      labels:
        app: otelcontribcol
    spec:
      serviceAccountName: otelcontribcol
      containers:
      - name: otelcontribcol
        # This image is created by running `make docker-otelcontribcol`.
        # If you are not building the collector locally, specify a published image: `otel/opentelemetry-collector-contrib`
        image: otelcontribcol:latest
        args: ["--config", "/etc/config/config.yaml"]
        volumeMounts:
        - name: config
          mountPath: /etc/config
        imagePullPolicy: IfNotPresent
      volumes:
        - name: config
          configMap:
            name: otelcontribcol
EOF

​
Conversion Example

The following K8s Event 
{
    "apiVersion": "v1",
    "count": 4,
    "eventTime": null,
    "firstTimestamp": "2025-09-08T06:20:41Z",
    "involvedObject": {
        "apiVersion": "v1",
        "fieldPath": "spec.containers{bad}",
        "kind": "Pod",
        "name": "bad-pod",
        "namespace": "default",
        "resourceVersion": "11326",
        "uid": "2c2a4312-12b4-4ef0-bba4-5295add58417"
    },
    "kind": "Event",
    "lastTimestamp": "2025-09-08T06:22:13Z",
    "message": "Pulling image \"nonexistentrepo/nonexistimage\"",
    "metadata": {
        "creationTimestamp": "2025-09-08T06:20:41Z",
        "name": "bad-pod.18633a5aeb89ba21",
        "namespace": "default",
        "resourceVersion": "11520",
        "uid": "86bc5e70-a921-4fbc-8b64-fa1316289423"
    },
    "reason": "Pulling",
    "reportingComponent": "kubelet",
    "reportingInstance": "kind-control-plane",
    "source": {
        "component": "kubelet",
        "host": "kind-control-plane"
    },
    "type": "Normal"
}
will be converted to the following log 
{
  "SchemaURL": "",
  "ResourceAttributes": {
    "k8s.node.name": "kind-control-plane",
    "k8s.object.kind": "Pod",
    "k8s.object.name": "bad-pod",
    "k8s.object.uid": "2c2a4312-12b4-4ef0-bba4-5295add58417",
    "k8s.object.fieldpath": "spec.containers{bad}",
    "k8s.object.api_version": "v1",
    "k8s.object.resource_version": "11326"
  },
  "ScopeLogs": [
    {
      "SchemaURL": "",
      "InstrumentationScope": {},
      "LogRecords": [
        {
          "ObservedTimestamp": "1970-01-01T00:00:00Z",
          "Timestamp": "2025-09-08T06:22:13Z",
          "SeverityText": "Normal",
          "SeverityNumber": 9,
          "Body": "Pulling image \"nonexistentrepo/nonexistimage\"",
          "Attributes": {
            "k8s.event.reason": "Pulling",
            "k8s.event.action": "",
            "k8s.event.start_time": "2025-09-08T06:20:41Z",
            "k8s.event.name": "bad-pod.18633a5aeb89ba21",
            "k8s.event.uid": "86bc5e70-a921-4fbc-8b64-fa1316289423",
            "k8s.namespace.name": "default",
            "k8s.event.count": 4
          },
          "TraceID": "",
          "SpanID": "",
          "Flags": 0
        }
      ]
    }
  ]
}

​
Configuration

​
Example Configuration

k8s_events:
k8s_events/all_settings:
  namespaces: [ default, my_namespace ]
Last generated: 2026-04-13