Customizing Agent - Kubernetes Monitoring

The Atatus Kubernetes Agent automatically discovers all namespaces and workloads upon installation. This guide outlines the various configuration options available to help you manage data collection, filter logs, and control pod scheduling across your cluster.

All configurations must be added to your atatus_values.yaml file.

Configuration Options

Use the parameters below to customize the agent's behavior:

General Configuration Example

Here is a comprehensive example demonstrating how to construct your atatus_values.yaml file:

# atatus_values.yaml
atatus:
  license_key: "lic_infra_*************"
  logs_enabled: true
  cluster_name: "my-production-cluster"
  log_level: "info"

  # Include/Exclude by namespace
  container_include: kube:preprod kube:staging
  container_exclude: kube:prod

  # Include/Exclude metrics by pod name
  container_include_metrics: kube_pod:^my-app-
  container_exclude_metrics: kube_container:^sidecar-proxy$

  # Include/Exclude logs by container name
  container_include_logs: kube_container:^my-app$
  container_exclude_logs: kube_container:^log-router$

  # Log line filtering
  container_include_log_lines:
    - '(?i)error'
  container_exclude_log_lines:
    - '(?i)healthcheck'

daemonset:
  enabled: true
  tolerations:
    - operator: "Exists"

Filter Prefixes

All container_include* and container_exclude* options (except _log_lines) require a prefix that tells the agent what to match against. The prefix is followed by the value to match, with no space after the colon. The value can be an exact string or a regular expression.

Note: On Kubernetes, use kube:, kube_pod:, and kube_container:. The name: and image: prefixes are intended for Docker hosts and behave inconsistently on Kubernetes:

• name: does not reliably match pods. Logs are filtered, but pod-level metrics continue to be collected for every pod in the cluster. Use kube_pod: instead.
• image: filters metrics only and has no effect on log collection. Use kube_container: to filter logs.

The value after the prefix also supports regular expressions:

# Match all namespaces starting with "dev-"
container_include: kube:^dev-.*

# Match all pods whose name starts with "api"
container_include: kube_pod:^api-

# Match all containers named exactly "nginx"
container_include: kube_container:^nginx$

A pattern cannot contain a space or a colon. Patterns containing either are ignored.

Matching Pod Names

Pods created by a Deployment carry a generated suffix that changes on every rollout — for example api-7d9f8b6c5d-x4k2p. If you match the full pod name, monitoring stops at your next deployment. Match the stable prefix instead:

# Correct — survives rollouts
container_include: kube_pod:^api-

# Avoid — breaks at the next deployment
container_include: kube_pod:^api-7d9f8b6c5d-x4k2p$

Use an exact match only for StatefulSet pods and static pods, whose names do not change:

container_include: kube_pod:^api-0$

Container names are defined in the pod spec and do not change, so they can always be matched exactly: kube_container:^nginx$.

Filtering by Multiple Values

To filter by multiple values, separate them with spaces:

container_include: kube:preprod kube:staging

This monitors the preprod and staging namespaces, and excludes everything else.

Filters within a single option always combine with OR — data is matched if it matches any of them. This applies across different prefixes too, so mixing prefixes widens the filter rather than narrowing it:

# This does NOT mean "the api pods in the prod namespace".
# It matches every api-* pod, PLUS everything in the prod namespace.
container_include: kube_pod:^api- kube:^prod$

Use a single prefix type per option.

Requiring Two Conditions

Each option is applied independently, so data must satisfy every option that applies to it. To require two conditions, combine the general option with the logs and metrics options:

# Only the api-* pods, and only in the prod namespace
container_include: kube:^prod$
container_include_logs: kube_pod:^api-
container_include_metrics: kube_pod:^api-

What the Filters Apply To

These filters apply to data belonging to a specific pod or container. Node-level and cluster-level data is not tied to any pod and continues to be collected.

This means your cluster health monitoring stays intact while pod-level detail narrows to the workloads you select.

Container Include & Exclude Filtering

Use container_include and container_exclude to control what is monitored for both logs and metrics. You can filter by namespace, pod name, or container name.

• Filter by namespace — monitor only the preprod and staging namespaces, and exclude the prod namespace:

container_include: kube:preprod kube:staging
container_exclude: kube:prod

• Filter by pod name — monitor only pods belonging to the my-app workload:

container_include: kube_pod:^my-app-

• Filter by container name — monitor everything except the sidecar-proxy container:

container_exclude: kube_container:^sidecar-proxy$

Container Metrics Filtering

Use container_include_metrics and container_exclude_metrics to control which containers are monitored for metrics only. Log collection is unaffected.

• Filter by pod name — collect metrics only from the my-app workload, and exclude the sidecar-proxy container:

container_include_metrics: kube_pod:^my-app-
container_exclude_metrics: kube_container:^sidecar-proxy$

• Filter by namespace — collect metrics only from the production namespace, and exclude the testing namespace:

container_include_metrics: kube:production
container_exclude_metrics: kube:testing

Container Logs Filtering

Use container_include_logs and container_exclude_logs to control which containers are monitored for logs only. Metric collection is unaffected.

• Filter by container name — collect logs only from my-app, and exclude the log-router container:

container_include_logs: kube_container:^my-app$
container_exclude_logs: kube_container:^log-router$

• Filter by pod name — collect logs only from pods belonging to the my-app workload:

container_include_logs: kube_pod:^my-app-

Note: The image: prefix has no effect on log collection. Use kube_container: or kube_pod: to filter logs.

Log Line Filtering

You can reduce log volume by filtering individual log lines at the agent level using regular expressions. Unlike the container-level filters above, these options match against the content of each log line, not the container name or namespace.

The (?i) prefix in a regular expression enables case-insensitive matching.

• Collect only log lines containing the word "error" (case-insensitive):

container_include_log_lines:
  - '(?i)error'

• Drop log lines containing the word "healthcheck" (case-insensitive):

container_exclude_log_lines:
  - '(?i)healthcheck'

Scheduling the Agent on Tainted Nodes

Kubernetes uses taints to restrict which pods can run on specific nodes (e.g., GPU or system nodes). To allow the Atatus Infrastructure Agent to run on tainted nodes, configure tolerations under the daemonset section in your atatus_values.yaml file.

To run the agent on every active node across your cluster, configure a wildcard toleration using the Exists operator:

daemonset:
  enabled: true
  tolerations:
    - operator: "Exists"

Targeting Specific Node Pools

To target specific node pools instead of bypassing all taints, define selective tolerations.

daemonset:
  enabled: true
  tolerations:
    # System node pools
    - key: "CriticalAddonsOnly"
      operator: "Exists"

    # GPU nodes
    - key: "sku"
      operator: "Equal"
      value: "gpu"
      effect: "NoSchedule"

    # Spot or preemptible nodes
    - key: "node.kubernetes.io/instance-type"
      operator: "Equal"
      value: "spot"
      effect: "NoSchedule"

    # Windows nodes (if applicable)
    - key: "node.kubernetes.io/os"
      operator: "Equal"
      value: "windows"
      effect: "NoSchedule"