--- title: "loki.source.podlogs | Grafana Agent documentation" description: "Learn about loki.source.podlogs" --- # loki.source.podlogs > **EXPERIMENTAL**: This is an [experimental](/docs/agent/v0.43/stability/#experimental) component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. `loki.source.podlogs` discovers `PodLogs` resources on Kubernetes and, using the Kubernetes API, tails logs from Kubernetes containers of Pods specified by the discovered them. `loki.source.podlogs` is similar to `loki.source.kubernetes`, but uses custom resources rather than being fed targets from another Flow component. > **NOTE**: Unlike `loki.source.kubernetes`, it is not possible to distribute responsibility of collecting logs across multiple Grafana Agents. To avoid collecting duplicate logs, only one Grafana Agent should be running a `loki.source.podlogs` component. > **NOTE**: Because `loki.source.podlogs` uses the Kubernetes API to tail logs, it uses more network traffic and CPU consumption of Kubelets than `loki.source.file`. Multiple `loki.source.podlogs` components can be specified by giving them different labels. ## Usage Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy loki.source.podlogs "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.podlogs` supports the following arguments: Expand table | Name | Type | Description | Default | Required | |--------------|----------------------|-------------------------------------------|---------|----------| | `forward_to` | `list(LogsReceiver)` | List of receivers to send log entries to. | | yes | `loki.source.podlogs` searches for `PodLogs` resources on Kubernetes. Each `PodLogs` resource describes a set of pods to tail logs from. ## PodLogs custom resource The `PodLogs` resource describes a set of Pods to collect logs from. > **NOTE**: `loki.source.podlogs` looks for `PodLogs` of `monitoring.grafana.com/v1alpha2`, and is not compatible with `PodLogs` from the Grafana Agent Operator, which are version `v1alpha1`. Expand table | Field | Type | Description | |--------------|-------------------------------------------------------------------------------------------------------|-----------------------------------------------| | `apiVersion` | string | `monitoring.grafana.com/v1alpha2` | | `kind` | string | `PodLogs` | | `metadata` | [ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta) | Metadata for the PodLogs. | | `spec` | [PodLogsSpec](#podlogsspec) | Definition of what Pods to collect logs from. | ### PodLogsSpec `PodLogsSpec` describes a set of Pods to collect logs from. Expand table | Field | Type | Description | |---------------------|-------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------| | `selector` | [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta) | Label selector of Pods to collect logs from. | | `namespaceSelector` | [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta) | Label selector of Namespaces that Pods can be discovered in. | | `relabelings` | [RelabelConfig](https://prometheus-operator.dev/docs/operator/api/#monitoring.coreos.com/v1.RelabelConfig) | Relabel rules to apply to discovered Pods. | If `selector` is left as the default value, all Pods are discovered. If `namespaceSelector` is left as the default value, all Namespaces are used for Pod discovery. The `relabelings` field can be used to modify labels from discovered Pods. The following meta labels are available for relabeling: - `__meta_kubernetes_namespace`: The namespace of the Pod. - `__meta_kubernetes_pod_name`: The name of the Pod. - `__meta_kubernetes_pod_ip`: The pod IP of the Pod. - `__meta_kubernetes_pod_label_`: Each label from the Pod. - `__meta_kubernetes_pod_labelpresent_`: `true` for each label from the Pod. - `__meta_kubernetes_pod_annotation_`: Each annotation from the Pod. - `__meta_kubernetes_pod_annotationpresent_`: `true` for each annotation from the Pod. - `__meta_kubernetes_pod_container_init`: `true` if the container is an `InitContainer`. - `__meta_kubernetes_pod_container_name`: Name of the container. - `__meta_kubernetes_pod_container_image`: The image the container is using. - `__meta_kubernetes_pod_ready`: Set to `true` or `false` for the Pod’s ready state. - `__meta_kubernetes_pod_phase`: Set to `Pending`, `Running`, `Succeeded`, `Failed` or `Unknown` in the lifecycle. - `__meta_kubernetes_pod_node_name`: The name of the node the pod is scheduled onto. - `__meta_kubernetes_pod_host_ip`: The current host IP of the pod object. - `__meta_kubernetes_pod_uid`: The UID of the Pod. - `__meta_kubernetes_pod_controller_kind`: Object kind of the Pod’s controller. - `__meta_kubernetes_pod_controller_name`: Name of the Pod’s controller. In addition to the meta labels, the following labels are exposed to tell `loki.source.podlogs` which container to tail: - `__pod_namespace__`: The namespace of the Pod. - `__pod_name__`: The name of the Pod. - `__pod_container_name__`: The container name within the Pod. - `__pod_uid__`: The UID of the Pod. ## Blocks The following blocks are supported inside the definition of `loki.source.podlogs`: Expand table | Hierarchy | Block | Description | Required | |--------------------------------------------|----------------------------------------------|------------------------------------------------------------------------------|----------| | client | [client](#client-block) | Configures Kubernetes client used to tail logs. | no | | client > basic\_auth | [basic\_auth](#basic_auth-block) | Configure basic\_auth for authenticating to the endpoint. | no | | client > authorization | [authorization](#authorization-block) | Configure generic authorization to the endpoint. | no | | client > oauth2 | [oauth2](#oauth2-block) | Configure OAuth2 for authenticating to the endpoint. | no | | client > oauth2 > tls\_config | [tls\_config](#tls_config-block) | Configure TLS settings for connecting to the endpoint. | no | | client > tls\_config | [tls\_config](#tls_config-block) | Configure TLS settings for connecting to the endpoint. | no | | selector | [selector](#selector-block) | Label selector for which `PodLogs` to discover. | no | | selector > match\_expression | [match\_expression](#match_expression-block) | Label selector expression for which `PodLogs` to discover. | no | | namespace\_selector | [selector](#selector-block) | Label selector for which namespaces to discover `PodLogs` in. | no | | namespace\_selector > match\_expression | [match\_expression](#match_expression-block) | Label selector expression for which namespaces to discover `PodLogs` in. | no | | clustering | [clustering](#clustering-block) | Configure the component for when Grafana Agent is running in clustered mode. | 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: Expand table | Name | Type | Description | Default | Required | |--------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------|----------| | `api_server` | `string` | URL of the Kubernetes API server. | | no | | `kubeconfig_file` | `string` | Path of the `kubeconfig` file to use for connecting to Kubernetes. | | 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 | | `proxy_url` | `string` | HTTP proxy to send requests through. | | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no | At most, one of the following can be provided: - [`bearer_token` argument](#client-block). - [`bearer_token_file` argument](#client-block). - [`basic_auth` block](#basic_auth-block). - [`authorization` block](#authorization-block). - [`oauth2` block](#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. ### basic\_auth block 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. ### authorization block 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. ### oauth2 block 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 | | `proxy_url` | `string` | HTTP proxy to send requests through. | | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | 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. 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 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` 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) ### selector block The `selector` block describes a Kubernetes label selector for `PodLogs` or Namespace discovery. The following arguments are supported: Expand table | Name | Type | Description | Default | Required | |----------------|---------------|---------------------------------------------------|---------|----------| | `match_labels` | `map(string)` | Label keys and values used to discover resources. | `{}` | no | When the `match_labels` argument is empty, all resources will be matched. ### match\_expression block The `match_expression` block describes a Kubernetes label match expression for `PodLogs` or Namespace discovery. The following arguments are supported: Expand table | Name | Type | Description | Default | Required | |------------|----------------|------------------------------------|---------|----------| | `key` | `string` | The label name to match against. | | yes | | `operator` | `string` | The operator to use when matching. | | yes | | `values` | `list(string)` | The values used when matching. | | no | The `operator` argument must be one of the following strings: - `"In"` - `"NotIn"` - `"Exists"` - `"DoesNotExist"` Both `selector` and `namespace_selector` can make use of multiple `match_expression` inner blocks which are treated as AND clauses. ### clustering block Expand table | Name | Type | Description | Default | Required | |-----------|--------|-----------------------------------------------------|---------|----------| | `enabled` | `bool` | Distribute log collection with other cluster nodes. | | yes | When Grafana Agent Flow is [using clustering](../../../concepts/clustering/), and `enabled` is set to true, then this `loki.source.podlogs` component instance opts-in to participating in the cluster to distribute the load of log collection between all cluster nodes. If Grafana Agent Flow is *not* running in clustered mode, then the block is a no-op and `loki.source.podlogs` collects logs based on every PodLogs resource discovered. ## Exported fields `loki.source.podlogs` does not export any fields. ## Component health `loki.source.podlogs` is only reported as unhealthy if given an invalid configuration. ## Debug information `loki.source.podlogs` exposes some target-level debug information per target: - The labels associated with the target. - The full set of labels which were found during service discovery. - The most recent time a log line was read and forwarded to the next components in the pipeline. - The most recent error from tailing, if any. ## Debug metrics `loki.source.podlogs` does not expose any component-specific debug metrics. ## Example This example discovers all `PodLogs` resources and forwards collected logs to a `loki.write` component so they are written to Loki. Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy loki.source.podlogs "default" { forward_to = [loki.write.local.receiver] } loki.write "local" { endpoint { url = env("LOKI_URL") } } ``` ## Compatible components `loki.source.podlogs` 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.