HTTP endpoint discovery

Kind: http

Overview

Netdata can pull a list of monitorable targets from any HTTP endpoint you control — a CMDB API, an internal asset registry, a static file served by nginx, or a Prometheus-style file_sd export. The discoverer fetches the endpoint, decodes JSON or YAML, and feeds each item into the services: rule engine. This is the “bring your own source-of-truth” discoverer.

This page covers HTTP-specific setup. For the broader Service Discovery model and the shared template-helper reference, see Service Discovery.

How it works

Each discovery cycle, the discoverer:

1. Fetches the configured url over HTTP/HTTPS, honouring all standard go.d collector HTTP options (auth, headers, TLS, proxy, timeout).
2. Decodes the response as either JSON or YAML according to format (auto / json / yaml). With format: auto, the decoder uses Content-Type if it is unambiguous, otherwise tries JSON first then YAML.
3. Accepts two shapes at the top level: a bare array ([ item, item, … ]) or an envelope ({ "items": [ … ] }). Anything else is rejected.
4. Builds one target per array element, exposing .Item (the decoded element — could be a string, a map, a number, …), .TUID, and .Hash.
5. Runs the services: rules against each target. The default stock rule passes the item through unchanged via the toYaml helper, so an endpoint that already serves go.d job configurations works with zero rule authoring.
6. Reconciles disappeared items — when a target is no longer in the response, the corresponding job stops on the next reconcile.

Limitations

• Only one URL per pipeline. To pull from multiple sources, configure multiple HTTP discovery pipelines (each as its own UI entry, or split the file into one job per source).
• Response size is capped at 10 MiB.
• One-shot mode (interval: 0) fetches a single time when the pipeline starts. It does not refetch on SD reload — recreate the pipeline to refresh.
• bearer_token_file under /var/run/secrets/ is treated as optional when Netdata is not running in Kubernetes (so the same config can be used in a Helm deployment without erroring out on dev hosts).
• The discoverer does not introspect the items it received — anything beyond what the upstream endpoint provides must be inferred via service rules.

Setup

You can configure the http discoverer in two ways:

Prerequisites

Endpoint that returns JSON or YAML

Stand up an HTTP endpoint that returns either a top-level array ([ "https://a/health", "https://b/health" ]) or an envelope ({ "items": [...] }). Items can be primitives (strings, numbers), maps, or any nestable value the rule engine knows how to consume.

Choose a pass-through vs. curated approach

• Pass-through: have your endpoint emit ready-made go.d job configurations and use the stock rule, which renders each item directly via toYaml. Zero rule authoring on the Netdata side.
• Curated: have your endpoint emit raw data (URLs, hostnames, tags) and write services: rules that map the data to the right collector module. More work, more flexibility.

Configuration

Options

The configuration file has two top-level blocks: discoverer: (the options below) and services: (rules that turn fetched items into collector jobs — see Service Rules).

After editing the file, restart the Netdata Agent to load the updated discovery pipeline.

url

Must be a fully-qualified http:// or https:// URL. The endpoint is expected to return either a bare array or an {"items": [...]} envelope (see Service Rules for the input model).

interval

Set to 0 for one-shot mode — the endpoint is fetched once when the pipeline starts and never again. SD reload does not retrigger; recreate the pipeline to refresh.

format

With auto, the decoder uses Content-Type when it is unambiguous (application/json, application/yaml, *+json, *+yaml), otherwise tries JSON first then YAML.

headers / username / password / bearer_token_file / proxy_url / tls_skip_verify / etc.

See any go.d HTTP-based collector (httpcheck, prometheus, nginx, …) for the full set. Notable: when bearer_token_file points under /var/run/secrets/ and Netdata is not running inside Kubernetes, missing token files are silently ignored.

via UI

1. Open the Netdata Dynamic Configuration UI.
2. Go to Collectors -> go.d -> ServiceDiscovery -> http.
3. Add a new discovery pipeline and give it a name.
4. Fill in the discoverer-specific settings and the service rules.
5. Save the discovery pipeline.

via File

Define the discovery pipeline in /etc/netdata/go.d/sd/http.conf.

The file has two top-level blocks: discoverer: (the options above) and services: (rules that turn discovered targets into collector jobs — see Service Rules).

After editing the file, restart the Netdata Agent to load the updated discovery pipeline.

Examples

Pass-through go.d jobs (stock rule)

The endpoint serves go.d job configurations directly. Each item must include a module field. The stock rule pipes the item through toYaml unchanged.

disabled: no
discoverer:
  http:
    url: https://cmdb.example.com/netdata/jobs.yaml
    interval: 5m
    format: auto
services:
  - id: passthrough
    match: '{{ true }}'
    config_template: |
      {{ .Item | toYaml }}      

Array of bare URLs → httpcheck

The endpoint returns [ "https://a/health", "https://b/health" ]. Map each URL to an httpcheck job.

disabled: no
discoverer:
  http:
    url: https://cmdb.example.com/netdata/health-urls.json
    interval: 1m
services:
  - id: httpcheck
    match: '{{ kindIs "string" .Item }}'
    config_template: |
      name: {{ .TUID }}
      url: {{ .Item }}      

Array of objects with custom shape

The endpoint returns [ { "name": "api", "url": "https://api.example.com/health" }, … ].

disabled: no
discoverer:
  http:
    url: https://cmdb.example.com/netdata/services.json
services:
  - id: httpcheck
    match: '{{ and (kindIs "map" .Item) (hasKey .Item "url") }}'
    config_template: |
      name: {{ .Item.name }}
      url: {{ .Item.url }}      

Bearer-token authentication

Authenticate against the source-of-truth endpoint using a bearer token from a file.

disabled: no
discoverer:
  http:
    url: https://cmdb.example.com/api/v1/netdata/jobs
    bearer_token_file: /etc/netdata/secrets/cmdb-token
    headers:
      Accept: application/yaml
services:
  - id: passthrough
    match: '{{ true }}'
    config_template: |
      {{ .Item | toYaml }}      

Troubleshooting

parse response as json: …; parse response as yaml: …

The response is neither valid JSON nor valid YAML. Common causes: the endpoint returned an HTML error page (check status code and Content-Type), the JSON has trailing garbage, or YAML indentation is wrong. Reproduce with curl -i to see the headers + body.

Items decoded but no jobs created

Your services: rules are not matching, or they match but the rendered template is empty. With pass-through ({{ .Item | toYaml }}), make sure each upstream item includes module: and name:. With curated rules, double-check the type checks (kindIs, hasKey).

TLS/certificate errors against an internal endpoint

Use tls_skip_verify: yes to bypass for testing, then mount the issuing CA and set tls_ca: /path/to/ca.crt for production.

Bearer token file not found

When Netdata runs outside Kubernetes and the configured bearer_token_file points under /var/run/secrets/, missing tokens are silently ignored — this is intentional so the same config works in dev and in Helm. If you are inside k8s, the file must exist.