Skip to main content

kubernetes_watch

Watches Kubernetes resources for changes, similar to kubectl get <resource> --watch.

Introduced in version 1.15.0.

# Common config fields, showing default values
input:
  label: ""
  kubernetes_watch:
    auto_auth: true
    kubeconfig: ""
    kubeconfig_yaml: ""
    context: ""
    namespaces: []
    label_selector: {}
    resource: ""
    event_types:
      - ADDED
      - MODIFIED
      - DELETED
    include_initial_list: true

This input watches Kubernetes resources and emits events when resources are added, modified, or deleted. It uses the Kubernetes discovery API to automatically resolve resource types, supporting both standard resources and Custom Resource Definitions (CRDs).

Watching Resources​

Specify any resource name recognized by the cluster:

input:
  kubernetes_watch:
    resource: pods

The resource name is resolved dynamically via the Kubernetes API, so any valid resource type is supported (pods, deployments, services, configmaps, or any installed CRD).

Explicit GVR for Custom Resources​

For custom resources where you need to specify the exact group/version:

input:
  kubernetes_watch:
    custom_resource:
      group: stable.example.com
      version: v1
      resource: crontabs

Watch Events​

Each message includes the watch event type in metadata:

  • ADDED: Resource was created
  • MODIFIED: Resource was updated
  • DELETED: Resource was removed

Metadata​

This input adds the following metadata fields to each message:

- kubernetes_watch_event_type
- kubernetes_resource_kind
- kubernetes_resource_name
- kubernetes_resource_namespace
- kubernetes_resource_version
- kubernetes_resource_uid
- kubernetes_resource_creation_timestamp

You can access these metadata fields using function interpolation.

Additionally, all resource labels are added as metadata with the prefix kubernetes_labels_, and all annotations are added with the prefix kubernetes_annotations_. For example, a label app: myapp becomes metadata key kubernetes_labels_app.

Fields​

auto_auth​

Automatically detect authentication method. Tries in-cluster config first, then falls back to kubeconfig.

Type: bool
Default: true

kubeconfig​

Path to kubeconfig file. If empty, uses $KUBECONFIG (if set) or the default kubeconfig location (~/.kube/config).

Type: string
Default: ""

kubeconfig_yaml​

Kubeconfig content as a YAML string. Use this to embed kubeconfig directly in your config (e.g., from a secret or environment variable) instead of referencing a file path.

Secret

This field contains sensitive information that usually shouldn't be added to a config directly, read our secrets page for more info.

Type: string
Default: ""

context​

Kubernetes context to use from kubeconfig. If empty, uses the current context.

Type: string
Default: ""

api_server​

Kubernetes API server URL. Only used when providing explicit credentials.

Type: string
Default: ""

token​

Bearer token for authentication. Can be a service account token.

Secret

This field contains sensitive information that usually shouldn't be added to a config directly, read our secrets page for more info.

Type: string
Default: ""

token_file​

Path to file containing bearer token.

Type: string
Default: ""

ca_file​

Path to CA certificate file for verifying API server.

Type: string
Default: ""

insecure_skip_verify​

Skip TLS certificate verification. Not recommended for production.

Type: bool
Default: false

client_qps​

QPS limit for Kubernetes API client. 0 uses the client-go default.

Type: float
Default: 0

client_burst​

Burst limit for Kubernetes API client. 0 uses the client-go default.

Type: int
Default: 0

namespaces​

Namespaces to watch. Empty list means all namespaces.

Type: array
Default: []

# Examples

namespaces:
  - default

namespaces:
  - production
  - staging

label_selector​

Kubernetes label selector to filter resources.

Type: object
Default: {}

# Examples

label_selector:
  app: myapp

label_selector:
  app: myapp
  env: prod

field_selector​

Kubernetes field selector to filter resources.

Type: object
Default: {}

# Examples

field_selector:
  status.phase: Running

field_selector:
  metadata.name: my-pod

request_timeout​

Timeout for Kubernetes API requests such as list calls. Use "0s" to disable.

Type: string
Default: "30s"

resource​

Standard Kubernetes resource type to watch.

Type: string
Default: ""

# Examples

resource: pods

resource: deployments

resource: configmaps

custom_resource​

Custom Resource Definition to watch. Use this for CRDs instead of 'resource'.

Type: object

custom_resource.group​

API group for the custom resource (e.g., 'stable.example.com').

Type: string
Default: ""

custom_resource.version​

API version for the custom resource (e.g., 'v1', 'v1beta1').

Type: string
Default: "v1"

custom_resource.resource​

Plural name of the custom resource (e.g., 'crontabs').

Type: string
Default: ""

event_types​

Watch event types to include. Valid values are ADDED, MODIFIED, and DELETED.

Type: array
Default: ["ADDED","MODIFIED","DELETED"]

# Examples

event_types:
  - ADDED
  - DELETED

event_types:
  - MODIFIED

include_initial_list​

Emit ADDED events for all existing resources when starting.

Type: bool
Default: true

max_retries​

The maximum number of retries before giving up on the request. If set to zero there is no discrete limit.

Type: int
Default: 0

backoff​

Control time intervals between retry attempts.

Type: object

backoff.initial_interval​

The initial period to wait between retry attempts.

Type: string
Default: "1s"

backoff.max_interval​

The maximum period to wait between retry attempts.

Type: string
Default: "60s"

backoff.max_elapsed_time​

The maximum period to wait before retry attempts are abandoned. If zero then no limit is used.

Type: string
Default: "0s"