Menu
Open source

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.

Multiple loki.source.kubernetes_events components can be specified by giving them different labels.

Usage

river
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.

loki.source.kubernetes_events supports the following arguments:

NameTypeDescriptionDefaultRequired
job_namestringValue to use for job label for generated logs."loki.source.kubernetes_events"no
log_formatstringFormat of the log."logfmt"no
namespaceslist(string)Namespaces to watch for Events in.[]no
forward_tolist(LogsReceiver)List of receivers to send log entries to.yes

By default, loki.source.kubernetes_events will watch 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 will be 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, Grafana Agent Flow must have permissions to watch events at the cluster scope (such as using a ClusterRoleBinding). If an explicit list of namespaces is provided, Grafana Agent Flow 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.

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

Blocks

The following blocks are supported inside the definition of loki.source.kubernetes_events:

HierarchyBlockDescriptionRequired
clientclientConfigures Kubernetes client used to tail logs.no
client > basic_authbasic_authConfigure basic_auth for authenticating to the endpoint.no
client > authorizationauthorizationConfigure generic authorization to the endpoint.no
client > oauth2oauth2Configure OAuth2 for authenticating to the endpoint.no
client > oauth2 > tls_configtls_configConfigure TLS settings for connecting to the endpoint.no
client > tls_configtls_configConfigure TLS settings for connecting to the endpoint.no

The > symbol indicates deeper levels of nesting. For example, client > basic_auth refers to a basic_auth block defined inside a client block.

client block

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 Grafana Agent pod is used.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
api_serverstringURL of the Kubernetes API server.no
kubeconfig_filestringPath of the kubeconfig file to use for connecting to Kubernetes.no
bearer_token_filestringFile containing a bearer token to authenticate with.no
bearer_tokensecretBearer token to authenticate with.no
enable_http2boolWhether HTTP2 is supported for requests.trueno
follow_redirectsboolWhether redirects returned by the server should be followed.trueno
proxy_urlstringHTTP proxy to send requests through.no
no_proxystringComma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.no
proxy_from_environmentboolUse the proxy URL indicated by environment variables.falseno
proxy_connect_headermap(list(secret))Specifies headers to send to proxies during CONNECT requests.no

At most, one of the following can be provided:

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.

basic_auth block

NameTypeDescriptionDefaultRequired
password_filestringFile containing the basic auth password.no
passwordsecretBasic auth password.no
usernamestringBasic auth username.no

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

authorization block

NameTypeDescriptionDefaultRequired
credentials_filestringFile containing the secret value.no
credentialssecretSecret value.no
typestringAuthorization type, for example, “Bearer”.no

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

oauth2 block

NameTypeDescriptionDefaultRequired
client_idstringOAuth2 client ID.no
client_secret_filestringFile containing the OAuth2 client secret.no
client_secretsecretOAuth2 client secret.no
endpoint_paramsmap(string)Optional parameters to append to the token URL.no
proxy_urlstringHTTP proxy to send requests through.no
no_proxystringComma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.no
proxy_from_environmentboolUse the proxy URL indicated by environment variables.falseno
proxy_connect_headermap(list(secret))Specifies headers to send to proxies during CONNECT requests.no
scopeslist(string)List of scopes to authenticate with.no
token_urlstringURL 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.

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 block

NameTypeDescriptionDefaultRequired
ca_pemstringCA PEM-encoded text to validate the server with.no
ca_filestringCA certificate to validate the server with.no
cert_pemstringCertificate PEM-encoded text for client authentication.no
cert_filestringCertificate file for client authentication.no
insecure_skip_verifyboolDisables validation of the server certificate.no
key_filestringKey file for client authentication.no
key_pemsecretKey PEM-encoded text for client authentication.no
min_versionstringMinimum acceptable TLS version.no
server_namestringServerName 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 is not 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)

Exported fields

loki.source.kubernetes_events does not 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 does not 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 Grafana Agent 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.

In the Static mode’s eventhandler integration, a cache_path argument is used to configure a positions file. In Flow mode, this argument is no longer necessary.

Example

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

river
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 = env("LOKI_URL")
  }
}

Compatible components

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

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.