Refine discovery implementation: E2E stability test, spec/auto_conf regeneration, and dependency floor

- Tighten E2E discovery metric assertions from at_least=0 to at_least=1
- Add discovery_overrides.py/discovery_strategies.py stub files
- Move ad_identifiers out of the spec discovery stanza and regenerate discovery.py/auto_conf.yaml
- Add test_e2e_discovery_all_candidates and fix the changelog filename to match PR #24118
- Add NGINX_CONFIG_FOLDER fallback in docker-compose so docker compose ps works without the env var set
- Bump datadog-checks-base floor to >=37.41.0, matching the version that introduced get_e2e_discovery_metadata, assert_all_discovery_candidates_stable, and candidate_ports

Author: martavicentenavarro

nginx/assets/configuration/spec.yaml

@@ -3,8 +3,6 @@ fleet_configurable: true
 files:
 - name: nginx.yaml
   discovery:
-    ad_identifiers:
-      - nginx
     strategies:
       - strategy: from_ports
         port_hints:
@@ -109,3 +107,11 @@ files:
     - type: file
       path: /var/log/nginx/error.log
       source: nginx
+
+- name: auto_conf.yaml
+  options:
+  - template: ad_identifiers
+    overrides:
+      value.example:
+      - nginx
+  - template: auto_conf/discovery

nginx/changelog.d/24097.added nginx/changelog.d/24118.addednginx/changelog.d/24097.added renamed to nginx/changelog.d/24118.added

@@ -7,22 +7,36 @@
 #     ddev -x validate config -s <INTEGRATION_NAME>
 #     ddev -x validate models -s <INTEGRATION_NAME>
 
+from __future__ import annotations
+
 from collections.abc import Iterator
 from typing import Any
 
-from datadog_checks.base.utils.discovery import Service, from_ports
+from datadog_checks.base.utils.discovery import Service, candidate_ports
+from datadog_checks.nginx.config_models import discovery_overrides
+from datadog_checks.nginx.config_models.instance import InstanceConfig
+from datadog_checks.nginx.config_models.shared import SharedConfig
 
 
-def candidates(service: Service) -> Iterator[dict[str, Any]]:
+def _generated_candidates(service: Service) -> Iterator[dict[str, Any]]:
+    shared = SharedConfig.model_validate({}, context={'configured_fields': frozenset()}).model_dump(
+        by_alias=True, mode='json', exclude_none=True
+    )
     # discovery[0]: from_ports
-    for ctx in from_ports(service, port_hints=[80]):
-        yield {
-            'init_config': {},
-            'instances': [
-                {
-                    'nginx_status_url': 'http://{service.host}:{port.number}/nginx_status'.format(
-                        service=service, **ctx
-                    ),
-                }
-            ],
+    for port in candidate_ports(service, [80]):
+        ctx = {'port': port}
+        instance_data = {
+            'nginx_status_url': 'http://{service.host}:{port.number}/nginx_status'.format(service=service, **ctx),
         }
+        instance = InstanceConfig.model_validate(
+            instance_data, context={'configured_fields': frozenset(instance_data)}
+        ).model_dump(by_alias=True, mode='json', exclude_none=True)
+        yield {'init_config': shared, 'instances': [instance]}
+
+
+def candidates(service: Service) -> Iterator[dict[str, Any]]:
+    override = getattr(discovery_overrides, 'candidates', None)
+    if override is None:
+        yield from _generated_candidates(service)
+    else:
+        yield from override(service, default=_generated_candidates)

nginx/datadog_checks/nginx/config_models/discovery.py

@@ -0,0 +1,12 @@
+# (C) Datadog, Inc. 2026-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+
+# Override the generated discovery candidates() for this integration.
+#
+# Define a candidates(service, default) function to wrap or replace the generated
+# candidate generation. `default` is the generated generator; call it to reuse
+# the spec-driven candidates, or ignore it to replace them entirely.
+#
+# def candidates(service, default):
+#     yield from default(service)

nginx/datadog_checks/nginx/config_models/discovery_overrides.py

@@ -0,0 +1,18 @@
+# (C) Datadog, Inc. 2026-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+
+# Here you can define custom (local:) discovery strategies for this integration.
+#
+# Decorate a generator with @discovery_strategy (imported from
+# datadog_checks.base.utils.discovery) and reference it from the spec discovery
+# stanza as `strategy: local:<function_name>`. The function receives the
+# discovered Service plus the inputs declared in the spec and yields one context
+# (ctx) mapping per candidate, exposing the keys listed in `provides`.
+#
+# from datadog_checks.base.utils.discovery import discovery_strategy
+#
+# @discovery_strategy(provides=('svc',))
+# def from_some_config(service, config_path):
+#     ...
+#     yield {'svc': ...}

nginx/datadog_checks/nginx/config_models/discovery_strategies.py

@@ -1,5 +1,19 @@
+## @param ad_identifiers - list of strings - required
+## A list of container identifiers that are used by Autodiscovery to identify
+## which container the check should be run against. For more information, see:
+## https://docs.datadoghq.com/agent/guide/ad_identifiers/
+#
 ad_identifiers:
   - nginx
+
+## Enables configuration discovery
+#
 discovery: {}
+
+## Unused init configuration
+#
 init_config:
+
+## Unused instance configuration
+#
 instances: []

nginx/datadog_checks/nginx/data/auto_conf.yaml

@@ -28,7 +28,7 @@ classifiers = [
     "Private :: Do Not Upload",
 ]
 dependencies = [
-    "datadog-checks-base>=37.33.0",
+    "datadog-checks-base>=37.41.0",
 ]
 dynamic = [
     "version",

nginx/pyproject.toml

@@ -2,7 +2,7 @@ services:
   nginx:
     image: ${NGINX_IMAGE}
     volumes:
-      - ${NGINX_CONFIG_FOLDER}:/etc/nginx
+      - ${NGINX_CONFIG_FOLDER:-/tmp}:/etc/nginx
     ports:
       - "8080:80"
       - "8081:443"

nginx/tests/docker/docker-compose.yaml

@@ -3,11 +3,20 @@
 # Licensed under Simplified BSD License (see LICENSE)
 import pytest
 
+from datadog_checks.dev.docker import assert_all_discovery_candidates_stable
 from datadog_checks.nginx import Nginx
 
 from . import common
 
 
+def _assert_nginx_metrics(aggregator):
+    for m in ('nginx.net.conn_dropped_per_s', 'nginx.net.conn_opened_per_s', 'nginx.net.request_per_s'):
+        aggregator.assert_metric(m, at_least=1)
+    for m in ('nginx.net.writing', 'nginx.net.reading', 'nginx.net.waiting', 'nginx.net.connections'):
+        aggregator.assert_metric(m, at_least=1)
+    aggregator.assert_service_check('nginx.can_connect', status=Nginx.OK)
+
+
 @pytest.mark.e2e
 @pytest.mark.skipif(common.USING_VTS, reason="Non-VTS test")
 def test_e2e(dd_agent_check, instance):
@@ -25,13 +34,13 @@ def test_e2e(dd_agent_check, instance):
 @pytest.mark.skipif(common.USING_VTS, reason="Non-VTS test")
 def test_e2e_discovery(dd_agent_check_discovery):
     aggregator = dd_agent_check_discovery(check_rate=True)
+    _assert_nginx_metrics(aggregator)
 
-    for m in ('nginx.net.conn_dropped_per_s', 'nginx.net.conn_opened_per_s', 'nginx.net.request_per_s'):
-        aggregator.assert_metric(m, at_least=0)
-    for m in ('nginx.net.writing', 'nginx.net.reading', 'nginx.net.waiting', 'nginx.net.connections'):
-        aggregator.assert_metric(m, at_least=0)
 
-    aggregator.assert_service_check('nginx.can_connect', status=Nginx.OK)
+@pytest.mark.e2e
+@pytest.mark.skipif(common.USING_VTS, reason="Non-VTS test")
+def test_e2e_discovery_all_candidates(dd_agent_check):
+    assert_all_discovery_candidates_stable(dd_agent_check, Nginx)
 
 
 @pytest.mark.e2e