---
title: "loki.source.kubernetes_events | Grafana Alloy documentation"
description: "Learn about loki.source.kubernetes_events"
---

# `loki.source.kubernetes_events`

`loki.source.kubernetes_events` tails events from the Kubernetes API and converts them into log lines to forward to other `loki` components.

You can specify multiple `loki.source.kubernetes_events` components by giving them different labels.

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
loki.source.kubernetes_events "<LABEL>" {
  forward_to = <RECEIVER_LIST>
}
```

## Arguments

The component starts a new reader for each of the given `targets` and fans out log entries to the list of receivers passed in `forward_to`.

You can use the following arguments with `loki.source.kubernetes_events`:

Expand table

| Name         | Type                 | Description                                      | Default                           | Required |
|--------------|----------------------|--------------------------------------------------|-----------------------------------|----------|
| `forward_to` | `list(LogsReceiver)` | List of receivers to send log entries to.        |                                   | yes      |
| `job_name`   | `string`             | Value to use for `job` label for generated logs. | `"loki.source.kubernetes_events"` | no       |
| `log_format` | `string`             | Format of the log.                               | `"logfmt"`                        | no       |
| `namespaces` | `list(string)`       | Namespaces to watch for Events in.               | `[]`                              | no       |

By default, `loki.source.kubernetes_events` watches for events in all namespaces. A list of explicit namespaces to watch can be provided in the `namespaces` argument.

By default, the generated log lines are in the `logfmt` format. Use the `log_format` argument to change it to `json`. These formats are also names of LogQL parsers, which can be used for processing the logs.

> Note
> 
> When watching all namespaces, Alloy must have permissions to watch events at the cluster scope (such as using a ClusterRoleBinding). If an explicit list of namespaces is provided, Alloy only needs permissions to watch events for those namespaces.

Log lines generated by `loki.source.kubernetes_events` have the following labels:

- `namespace`: Namespace of the Kubernetes object involved in the event.
- `job`: Value specified by the `job_name` argument.
- `instance`: Value matching the component ID.

If `job_name` argument is the empty string, the component will fail to load. To remove the job label, forward the output of `loki.source.kubernetes_events` to [a `loki.relabel` component](../loki.relabel/).

For compatibility with the `eventhandler` integration from static mode, `job_name` can be set to `"integrations/kubernetes/eventhandler"`.

## Blocks

You can use the following blocks with `loki.source.kubernetes_events`:

No valid configuration blocks found.

### `client`

The `client` block configures the Kubernetes client used to tail logs from containers. If the `client` block isn’t provided, the default in-cluster configuration with the service account of the running Alloy Pod is used.

The following arguments are supported:

Expand table

| Name                     | Type                | Description                                                                                      | Default | Required |
|--------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------|----------|
| `api_server`             | `string`            | URL of the Kubernetes API server.                                                                |         | no       |
| `bearer_token_file`      | `string`            | File containing a bearer token to authenticate with.                                             |         | no       |
| `bearer_token`           | `secret`            | Bearer token to authenticate with.                                                               |         | no       |
| `enable_http2`           | `bool`              | Whether HTTP2 is supported for requests.                                                         | `true`  | no       |
| `follow_redirects`       | `bool`              | Whether redirects returned by the server should be followed.                                     | `true`  | no       |
| `http_headers`           | `map(list(secret))` | Custom HTTP headers to be sent along with each request. The map key is the header name.          |         | no       |
| `kubeconfig_file`        | `string`            | Path of the `kubeconfig` file to use for connecting to Kubernetes.                               |         | no       |
| `no_proxy`               | `string`            | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. |         | no       |
| `proxy_connect_header`   | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests.                                    |         | no       |
| `proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                            | `false` | no       |
| `proxy_url`              | `string`            | HTTP proxy to send requests through.                                                             |         | no       |

At most, one of the following can be provided:

- \[`authorization`]\[authorization] block
- \[`basic_auth`]\[basic\_auth] block
- \[`bearer_token_file`]\[client] argument
- \[`bearer_token`]\[client] argument
- \[`oauth2`]\[oauth2] block

`no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured.

`proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY, and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured.

`proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured.

### `authorization`

Expand table

| Name               | Type     | Description                                | Default | Required |
|--------------------|----------|--------------------------------------------|---------|----------|
| `credentials_file` | `string` | File containing the secret value.          |         | no       |
| `credentials`      | `secret` | Secret value.                              |         | no       |
| `type`             | `string` | Authorization type, for example, “Bearer”. |         | no       |

`credential` and `credentials_file` are mutually exclusive, and only one can be provided inside an `authorization` block.

> Warning
> 
> Using `credentials_file` causes the file to be read on every outgoing request. Use the `local.file` component with the `credentials` attribute instead to avoid unnecessary reads.

### `basic_auth`

Expand table

| Name            | Type     | Description                              | Default | Required |
|-----------------|----------|------------------------------------------|---------|----------|
| `password_file` | `string` | File containing the basic auth password. |         | no       |
| `password`      | `secret` | Basic auth password.                     |         | no       |
| `username`      | `string` | Basic auth username.                     |         | no       |

`password` and `password_file` are mutually exclusive, and only one can be provided inside a `basic_auth` block.

> Warning
> 
> Using `password_file` causes the file to be read on every outgoing request. Use the `local.file` component with the `password` attribute instead to avoid unnecessary reads.

### `oauth2`

Expand table

| Name                     | Type                | Description                                                                                      | Default | Required |
|--------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------|----------|
| `client_id`              | `string`            | OAuth2 client ID.                                                                                |         | no       |
| `client_secret_file`     | `string`            | File containing the OAuth2 client secret.                                                        |         | no       |
| `client_secret`          | `secret`            | OAuth2 client secret.                                                                            |         | no       |
| `endpoint_params`        | `map(string)`       | Optional parameters to append to the token URL.                                                  |         | no       |
| `no_proxy`               | `string`            | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. |         | no       |
| `proxy_connect_header`   | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests.                                    |         | no       |
| `proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                            | `false` | no       |
| `proxy_url`              | `string`            | HTTP proxy to send requests through.                                                             |         | no       |
| `scopes`                 | `list(string)`      | List of scopes to authenticate with.                                                             |         | no       |
| `token_url`              | `string`            | URL to fetch the token from.                                                                     |         | no       |

`client_secret` and `client_secret_file` are mutually exclusive, and only one can be provided inside an `oauth2` block.

> Warning
> 
> Using `client_secret_file` causes the file to be read on every outgoing request. Use the `local.file` component with the `client_secret` attribute instead to avoid unnecessary reads.

The `oauth2` block may also contain a separate `tls_config` sub-block.

`no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured.

`proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY, and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured.

`proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured.

### `tls_config`

Expand table

| Name                   | Type     | Description                                              | Default | Required |
|------------------------|----------|----------------------------------------------------------|---------|----------|
| `ca_pem`               | `string` | CA PEM-encoded text to validate the server with.         |         | no       |
| `ca_file`              | `string` | CA certificate to validate the server with.              |         | no       |
| `cert_pem`             | `string` | Certificate PEM-encoded text for client authentication.  |         | no       |
| `cert_file`            | `string` | Certificate file for client authentication.              |         | no       |
| `insecure_skip_verify` | `bool`   | Disables validation of the server certificate.           |         | no       |
| `key_file`             | `string` | Key file for client authentication.                      |         | no       |
| `key_pem`              | `secret` | Key PEM-encoded text for client authentication.          |         | no       |
| `min_version`          | `string` | Minimum acceptable TLS version.                          |         | no       |
| `server_name`          | `string` | ServerName extension to indicate the name of the server. |         | no       |

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

- `ca_pem` and `ca_file`
- `cert_pem` and `cert_file`
- `key_pem` and `key_file`

When configuring client authentication, both the client certificate (using `cert_pem` or `cert_file`) and the client key (using `key_pem` or `key_file`) must be provided.

When `min_version` isn’t provided, the minimum acceptable TLS version is inherited from Go’s default minimum version, TLS 1.2. If `min_version` is provided, it must be set to one of the following strings:

- `"TLS10"` (TLS 1.0)
- `"TLS11"` (TLS 1.1)
- `"TLS12"` (TLS 1.2)
- `"TLS13"` (TLS 1.3)

### `clustering`

Expand table

| Name      | Type   | Description                                           | Default | Required |
|-----------|--------|-------------------------------------------------------|---------|----------|
| `enabled` | `bool` | Distribute event collection with other cluster nodes. |         | yes      |

When Alloy is [using clustering](../../../../get-started/clustering/), and `enabled` is set to true, then this `loki.source.kubernetes_events` component instance opts-in to participating in the cluster to distribute the load of event collection between all cluster nodes.

If Alloy is *not* running in clustered mode, then the block is a no-op and `loki.source.kubernetes_events` collects events from every configured namespace.

When clustering is enabled, each namespace is distributed across cluster nodes using consistent hashing. If the `namespaces` argument is empty (watching all namespaces), only a single node in the cluster will collect events, since all replicas share the same “all namespaces” target. If specific namespaces are listed, they are distributed across the available cluster nodes.

> Caution
> 
> When a namespace moves from one cluster node to another (for example, during a rollout or pod restart), the new node may re-deliver events that were already sent by the previous node. This is because each node tracks its read position locally, and the new node starts from the beginning of the available events. The impact is bounded by the Kubernetes event TTL, which defaults to one hour. See [issue #3717](https://github.com/grafana/alloy/issues/3717) for more details.

## Exported fields

`loki.source.kubernetes_events` doesn’t export any fields.

## Component health

`loki.source.kubernetes_events` is only reported as unhealthy if given an invalid configuration.

## Debug information

`loki.source.kubernetes_events` exposes the most recently read timestamp for events in each watched namespace.

## Debug metrics

`loki.source.kubernetes_events` doesn’t expose any component-specific debug metrics.

## Component behavior

The component uses its data path, a directory named after the domain’s fully qualified name, to store its *positions file*. The positions file is used to store read offsets, so that if a component or Alloy restarts, `loki.source.kubernetes_events` can pick up tailing from the same spot.

The data path is inside the directory configured by the `--storage.path` [command line argument](../../../cli/run/).

## Example

This example collects watches events in the `kube-system` namespace and forwards them to a `loki.write` component so they’re written to Loki.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
loki.source.kubernetes_events "example" {
  // Only watch for events in the kube-system namespace.
  namespaces = ["kube-system"]

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = sys.env("LOKI_URL")
  }
}
```

## Compatible components

`loki.source.kubernetes_events` can accept arguments from the following components:

- Components that export [Loki `LogsReceiver`](../../../compatibility/#loki-logsreceiver-exporters)

> Note
> 
> Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.