diff --git a/content/en/containers/guide/ad_identifiers.md b/content/en/containers/guide/ad_identifiers.md index 97bd86f9086..46966c8ea36 100644 --- a/content/en/containers/guide/ad_identifiers.md +++ b/content/en/containers/guide/ad_identifiers.md @@ -64,11 +64,11 @@ This matches **any** container images on your host that match `httpd` **or** `my ## Custom Autodiscovery container identifiers -If you want to apply different configuration templates to containers running the same image, use custom container identifiers. +If you want to apply different configuration templates to containers running the same image, use custom container identifiers. 1. Supply a custom container identifier to your container using a Docker label or Kubernetes annotation. - **Example**: + **Example**: Apply a Docker label or Kubernetes annotation to identify your container as `foo`: {{< tabs >}} @@ -95,7 +95,7 @@ If you want to apply different configuration templates to containers running the 2. Reference this custom value in your Autodiscovery configuration template. - **Example**: + **Example**: The following Apache Autodiscovery configuration template designates a container image with the custom name `foo`: ```yaml @@ -109,9 +109,98 @@ If you want to apply different configuration templates to containers running the service: webapp ``` +## Advanced container identifiers + +For use cases which require further granularity on Agent v7.73.0+, you can use the `cel_selector` check configuration option to target specific containers based on additional container attributes. These rules are based on the [Common Expression Language][3] syntax. + +Note: To be a valid Autodiscovery configuration, the check configuration must either include an `ad_identifier` or `cel_selector` container rule with the `container.image.reference` parameter. + +**Example**: +The following NGINX Autodiscovery configuration template designates a container image with the name `nginx` on two selected namespaces. Separately listed conditions are joined together through an **OR** operation. + +```yaml +ad_identifiers: + - nginx +cel_selector: + containers: + - container.pod.namespace == "target-ns-1" + - container.pod.namespace == "target-ns-2" +``` + +| Attribute | Description | +|------------------------------|------------------------------------------------------------| +| `container.name` | The name of the container. | +| `container.image.reference` | The full reference of the container image (registry, repo, tag/digest). | +| `container.pod.name` | The name of the pod running the container. | +| `container.pod.namespace` | The Kubernetes namespace of the pod. | +| `container.pod.annotations` | The annotations applied to the pod (key-value map). | + +These attributes can be used with the [CEL syntax][4] to define rules to select specific containers for check scheduling. Below is a list of example rules that could be defined: + +### Examples + +To select the container running the image `nginx` with a specific pod annotation: + +```yaml +ad_identifiers: + - nginx +cel_selector: + containers: + - container.pod.annotations["monitoring"] == "true" +``` + +To select the container running the image `nginx` in namespaces without the substring `-dev`: + +```yaml +ad_identifiers: + - nginx +cel_selector: + containers: + - !container.pod.namespace.matches("-dev") +``` + +To select the container running the image `nginx` with the container name `nginx-server` only in the namespace `prod`: + +```yaml +ad_identifiers: + - nginx +cel_selector: + containers: + - container.name == "nginx-server" && container.pod.namespace == "prod" +``` + +To select the container running an image with the substring `nginx`: + +```yaml +cel_selector: + containers: + - container.image.reference.matches("nginx") +``` + +To select containers using grouped logic (for example, a specific container name in either of two namespaces): + +```yaml +ad_identifiers: + - nginx +cel_selector: + containers: + - container.name == "my-app" && (container.pod.namespace == "production" || container.pod.namespace == "staging") +``` + +
+ +Broad conditions can unintentionally target containers on your host. For example, using a containers `cel_selector` like `!container.image.reference.matches("nginx")` selects **every** container on the host except nginx, including system components and likely unrelated applications. This can lead to additional telemetry collection which can impact billing. + +
+ +To globally exclude particular workloads from being collected regardless of the check integration, see the [Container Discovery Management][5] documentation. + ## Further Reading {{< partial name="whats-next/whats-next.html" >}} [1]: /getting_started/containers/autodiscovery [2]: /glossary/#short-image +[3]: https://cel.dev/ +[4]: https://github.com/google/cel-spec/blob/master/doc/langdef.md +[5]: /containers/guide/container-discovery-management