[float]
[[kubernetes-indexers-and-matchers]]
=== Indexers and matchers

==== Indexers

Indexers use pods metadata to create unique identifiers for each one of the
pods.

Available indexers are:

`container`:: Identifies the pod metadata using the IDs of its containers.
`ip_port`:: Identifies the pod metadata using combinations of its IP and its exposed ports.
When using this indexer metadata is identified using the IP of the pods, and the
combination if `ip:port` for each one of the ports exposed by its containers.
`pod_name`:: Identifies the pod metadata using its namespace and its name as
`namespace/pod_name`.
`pod_uid`:: Identifies the pod metadata using the UID of the pod.

==== Matchers

Matchers are used to construct the lookup keys that match with the identifiers
created by indexes.

===== `field_format`

Looks up pod metadata using a key created with a string format that can include
event fields.

This matcher has an option `format` to define the string format. This string
format can contain placeholders for any field in the event.

For example, the following configuration uses the `ip_port` indexer to identify
the pod metadata by combinations of the pod IP and its exposed ports, and uses
the destination IP and port in events as match keys:

[source,yaml]
-------------------------------------------------------------------------------
processors:
- add_kubernetes_metadata:
    ...
    default_indexers.enabled: false
    default_matchers.enabled: false
    indexers:
      - ip_port:
    matchers:
      - field_format:
          format: '%{[destination.ip]}:%{[destination.port]}'
-------------------------------------------------------------------------------

===== `fields`

Looks up pod metadata using as key the value of some specific fields. When
multiple fields are defined, the first one included in the event is used.

This matcher has an option `lookup_fields` to define the files whose value will
be used for lookup.

For example, the following configuration uses the `ip_port` indexer to identify
pods, and defines a matcher that uses the destination IP or the server IP for the
lookup, the first it finds in the event:

[source,yaml]
-------------------------------------------------------------------------------
processors:
- add_kubernetes_metadata:
    ...
    default_indexers.enabled: false
    default_matchers.enabled: false
    indexers:
      - ip_port:
    matchers:
      - fields:
          lookup_fields: ['destination.ip', 'server.ip']
-------------------------------------------------------------------------------

ifdef::has_kubernetes_logs_path_matcher[]
===== `logs_path`

Looks up pod metadata using identifiers extracted from the log path stored in
the `log.file.path` field.

This matcher has the following configuration settings:

`logs_path`:: (Optional) Base path of container logs. If not specified, it uses
the default logs path of the platform where {beatname_uc} is running: for Linux -
`/var/lib/docker/containers/`, Windows - `C:\\ProgramData\\Docker\\containers`.
To change the default value: container ID must follow right after the `logs_path` -
`<log_path>/<container_id>`, where `container_id` is a 64-character-long
hexadecimal string.

`resource_type`:: (Optional) Type of the resource to obtain the ID of.
Valid `resource_type`:
* `pod`: to make the lookup based on the pod UID. When `resource_type` is set to
`pod`, `logs_path` must be set as well, supported path in this case:
** `/var/lib/kubelet/pods/` used to read logs from mounted into the pod volumes,
those logs end up under `/var/lib/kubelet/pods/<pod UID>/volumes/<volume name>/...`
To use `/var/lib/kubelet/pods/` as a `log_path`, `/var/lib/kubelet/pods` must be
mounted into the filebeat Pods.
** `/var/log/pods/`
Note: when using `resource_type: 'pod'` logs will be enriched only with pod
metadata: pod id, pod name, etc., not container metadata.
* `container`: to make the lookup based on the container ID, `logs_path` must
be set to `/var/log/containers/`.
It defaults to `container`.

To be able to use `logs_path` matcher filebeat input path must be a subdirectory
of directory defined in `logs_path` configuration setting.

The default configuration is able to lookup the metadata using the container ID
when the logs are collected from the default docker logs path
(`/var/lib/docker/containers/<container ID>/...` on Linux).

For example the following configuration would use the pod UID when the logs are
collected from `/var/lib/kubelet/pods/<pod UID>/...`.

[source,yaml]
-------------------------------------------------------------------------------
processors:
- add_kubernetes_metadata:
    ...
    default_indexers.enabled: false
    default_matchers.enabled: false
    indexers:
      - pod_uid:
    matchers:
      - logs_path:
          logs_path: '/var/lib/kubelet/pods'
          resource_type: 'pod'
-------------------------------------------------------------------------------
endif::has_kubernetes_logs_path_matcher[]
