Kubernetes Cluster Events

The Kubernetes Cluster Events source collects events from the Kubernetes API server and emits them as log records. It uses the OpenTelemetry k8seventsreceiver, which continuously watches the API server for new and updated events. The configured cluster name is added to each record as the k8s.cluster.name resource attribute. The collector runs in-cluster as a Deployment and authenticates with the API server using its ServiceAccount.

Supported Telemetry Types

Platform	Metrics	Logs	Traces
Kubernetes Cluster		✓
OpenShift Cluster		✓

Prerequisites

This source runs in-cluster and reads events through the Kubernetes API server. The collector's ServiceAccount must be granted read access to events.

• A ServiceAccount for the collector Deployment.
• A ClusterRole granting get, list, and watch on the events resource in the core API group.
• A ClusterRoleBinding (or a namespace-scoped RoleBinding when watching specific namespaces) that binds the ClusterRole to the collector's ServiceAccount.

The receiver uses auth_type: serviceAccount, so no kubeconfig or static credentials are required. See the Kubernetes Using RBAC Authorization guide for details.

Configuration

Logs

Parameter	Type	Required	Default	Description
Cluster Name	String	Yes	(empty)	The cluster name which will be added as the k8s.cluster.name resource attribute.
Namespaces	Strings	No	(empty)	Optional namespaces to collect events from. Defaults to all namespaces.

Examples

Grant the collector read access to events

The collector authenticates to the API server with its ServiceAccount. Apply a ClusterRole and ClusterRoleBinding granting read access to events, then reference the ServiceAccount from the collector Deployment.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: bindplane-agent-events
rules:
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: bindplane-agent-events
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: bindplane-agent-events
subjects:
  - kind: ServiceAccount
    name: bindplane-agent
    namespace: bindplane-agent

Collect events from specific namespaces only

To restrict collection, set the Namespaces parameter to the namespaces you want to watch. Leaving it empty watches all namespaces.

apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: kubernetes-cluster-events
spec:
  type: k8s_events
  parameters:
    - name: cluster_name
      value: production-us-east
    - name: namespaces
      value:
        - default
        - kube-system

Configuration Tips

• Set a meaningful Cluster Name. It is written as the k8s.cluster.name resource attribute and is how downstream destinations distinguish events from multiple clusters.
• Leave Namespaces empty to collect from every namespace. Populate it only when you need to narrow collection to specific namespaces.
• The receiver collects events as they arrive after the collector starts. It does not backfill events that occurred before startup.

Troubleshooting

No events are collected

Symptoms: the source is configured but no event log records appear at the destination.

Solutions:

1. Confirm the collector Deployment references the ServiceAccount that is bound to the events ClusterRole.
2. If Namespaces is set, verify the events you expect are occurring in those namespaces. Clear the field to collect from all namespaces.

RBAC "forbidden" errors in the collector logs

Symptoms: collector logs show events is forbidden or cannot list/watch resource "events".

Solutions:

1. Verify the ClusterRole grants get, list, and watch on events in the core API group (apiGroups: [""]).
2. Confirm the ClusterRoleBinding (or RoleBinding) binds that ClusterRole to the collector's ServiceAccount in the correct namespace.

Standalone Source

apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: kubernetes-cluster-events
spec:
  type: k8s_events
  parameters:
    - name: cluster_name
      value: production-us-east
    - name: namespaces
      value: []

Related Resources

• OpenTelemetry Kubernetes Events Receiver (k8seventsreceiver)
• Kubernetes — Using RBAC Authorization