Docker discovery

Kind: docker

Overview

Netdata can automatically discover running Docker containers on the local Docker daemon and generate collector jobs for the services running inside them. The discoverer queries the Docker API on a fixed interval, builds one target per container port, and applies your services: rules to render collector job YAML — typically picking the right go.d module from the container image (nginx, postgres, redis, …).

This page covers Docker-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. Calls ContainerList on the Docker API at the configured address.
2. Builds one target per (container, network, port) triple for every container that has at least one network and at least one published port. Containers running in network: host mode are intentionally skipped — those are picked up by the net_listeners discoverer instead.
3. Exposes target fields: .Name, .Image, .Command, .Labels, .PrivatePort, .PublicPort, .PublicPortIP, .PortProtocol, .NetworkMode, .NetworkDriver, .IPAddress, .Address (the convenience IPAddress:PrivatePort).
4. Runs the services: rules against each target. The default stock conf carries curated rules for ~40 popular images (nginx, postgres, redis, rabbitmq, etc.) keyed on .Image patterns.
5. Reconciles disappeared containers — when a container exits, its target is removed and the corresponding collector job stops on the next reconcile.

Limitations

• Containers in network: host mode are not produced as Docker targets. Configure the net_listeners discoverer to pick them up via the host’s process table.
• Only TCP ports are typically useful; the stock conf’s first rule explicitly skips non-TCP, missing-port, and IPv6-mapped entries.
• Only published ports appear as targets. A container that exposes ports only inside a Docker network without -p mapping still produces a target via its private port and network IP.
• The discoverer reads the live container list; it does not inspect image manifests, healthcheck output, or process tables inside the container. Anything beyond labels/image/ports must be inferred via service rules.
• Only the local Docker daemon is supported (Unix socket or TCP). There is no docker-swarm or remote-cluster discovery mode.

Setup

You can configure the docker discoverer in two ways:

Prerequisites

Access to the Docker socket

The Netdata Agent must be able to reach the Docker daemon. The default address is unix:///var/run/docker.sock. If you run Netdata in a container, mount the socket: -v /var/run/docker.sock:/var/run/docker.sock:ro. The Netdata user (or the container) must have read access to the socket.

Discovery is enabled by default

The stock conf at /etc/netdata/go.d/sd/docker.conf ships with disabled: no and a curated set of services: rules covering ~40 popular images. To turn discovery off, set disabled: yes at the top of the file.

Configuration

Options

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

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

address

Supports both Unix-socket (unix:///var/run/docker.sock) and TCP (tcp://hostname:2375) endpoints.

If unset, Netdata also honors the DOCKER_HOST environment variable when present.

via UI

1. Open the Netdata Dynamic Configuration UI.
2. Go to Collectors -> go.d -> ServiceDiscovery -> docker.
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/docker.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

Default (Unix socket)

Use the default local Docker socket and the stock services rules.

disabled: no
discoverer:
  docker:
    address: unix:///var/run/docker.sock
services:
  # See the stock conf for the full curated rule set.
  - id: skip
    match: |
      {{ or (eq .NetworkMode "host") (not (eq .PortProtocol "tcp")) (empty .PrivatePort) }}      
  - id: nginx
    match: '{{ match "sp" .Image "nginx nginx:*" }}'
    config_template: |
      name: docker_{{.Name}}
      url: http://{{.Address}}/stub_status      

Remote daemon over TCP

Point the discoverer at a remote Docker daemon. TLS is not yet wired into the discoverer; either expose the daemon on a trusted internal network or use a stunnel/socat proxy.

disabled: no
discoverer:
  docker:
    address: tcp://docker.internal:2375
    timeout: 5s
services:
  - id: skip
    match: '{{ or (eq .NetworkMode "host") (not (eq .PortProtocol "tcp")) (empty .PrivatePort) }}'
  - id: redis
    match: '{{ match "sp" .Image "redis redis:* */redis */redis:*" }}'
    config_template: |
      name: docker_{{.Name}}
      address: redis://@{{.Address}}      

Troubleshooting

Permission denied on docker.sock

The Netdata user must be able to read the Docker socket. On a typical Linux host:

sudo usermod -aG docker netdata
systemctl restart netdata

In containers, mount the socket read-only and verify the file is readable from inside.

No targets discovered for containers in host networking

host-mode containers are intentionally skipped by the Docker discoverer. Enable the net_listeners discoverer instead — it picks up locally-listening processes, which includes host-mode containers.

Wrong module picked for an image

Stock rules match on .Image patterns. Custom forks or in-house image names won’t match. Add a rule above the stock catch-alls keyed on your own image name (match "sp" .Image "myorg/nginx myorg/nginx:*") or use a .Labels-driven rule.

Generated jobs fail to start

Common causes: the rendered URL is not reachable from the agent (different network, firewall); credentials baked into the template are wrong; the module’s port is not the one Docker reported. Check the rendered job YAML in the agent’s debug output.