Menu

Caution

Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow Grafana Agentbreadcrumb arrow Grafana Agent Flowbreadcrumb arrow Referencebreadcrumb arrow Componentsbreadcrumb arrow discovery.docker
Open source

discovery.docker

discovery.docker discovers Docker Engine containers and exposes them as targets.

Usage

river 
discovery.docker "LABEL" {
  host = "DOCKER_ENGINE_HOST"
}

Arguments

The following arguments are supported:

NameTypeDescriptionDefaultRequired
hoststringAddress of the Docker Daemon to connect to.yes
portnumberPort to use for collecting metrics when containers don’t have any port mappings.80no
host_networking_hoststringHost to use if the container is in host networking mode."localhost"no
refresh_intervaldurationFrequency to refresh list of containers."1m"no

Blocks

The following blocks are supported inside the definition of discovery.docker:

HierarchyBlockDescriptionRequired
filterfilterFilters discoverable resources.no
http_client_confighttp_client_configHTTP client configuration for docker requests.no
http_client_config > basic_authbasic_authConfigure basic_auth for authenticating to the endpoint.no
http_client_config > authorizationauthorizationConfigure generic authorization to the endpoint.no
http_client_config > oauth2oauth2Configure OAuth2 for authenticating to the endpoint.no
http_client_config > oauth2 > tls_configtls_configConfigure TLS settings for connecting to the endpoint.no

The > symbol indicates deeper levels of nesting. For example, http_client_config > basic_auth refers to a basic_auth block defined inside an http_client_config block.

filter block

The filter block configures a filter to pass to the Docker Engine to limit the amount of containers returned. The filter block can be specified multiple times to provide more than one filter.

NameTypeDescriptionDefaultRequired
namestringFilter name to use.yes
valueslist(string)Values to pass to the filter.yes

Refer to List containers from the Docker Engine API documentation for the list of supported filters and their meaning.

http_client_config block

The http_client_config block configures settings used to connect to the Docker Engine API server.

NameTypeDescriptionDefaultRequired
bearer_tokensecretBearer token to authenticate with.no
bearer_token_filestringFile containing a bearer token to authenticate with.no
proxy_urlstringHTTP proxy to proxy requests through.no
follow_redirectsboolWhether redirects returned by the server should be followed.trueno
enable_http_2boolWhether HTTP2 is supported for requests.trueno

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

NameTypeDescriptionDefaultRequired
usernamestringBasic auth username.no
passwordsecretBasic auth password.no
password_filestringFile containing the basic auth password.no

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

NameTypeDescriptionDefaultRequired
typestringAuthorization type, for example, “Bearer”.no
credentialsecretSecret value.no
credentials_filestringFile containing the secret value.no

credential and credentials_file are mutually exclusive and only one can be provided inside of an authorization block.

oauth2 block

NameTypeDescriptionDefaultRequired
client_idstringOAuth2 client ID.no
client_secretsecretOAuth2 client secret.no
client_secret_filestringFile containing the OAuth2 client secret.no
scopeslist(string)List of scopes to authenticate with.no
token_urlstringURL to fetch the token from.no
endpoint_paramsmap(string)Optional parameters to append to the token URL.no
proxy_urlstringOptional proxy URL for OAuth2 requests.no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

NameTypeDescriptionDefaultRequired
ca_filestringCA certificate to validate the server with.no
cert_filestringCertificate file for client authentication.no
key_filestringKey file for client authentication.no
server_namestringServerName extension to indicate the name of the server.no
insecure_skip_verifyboolDisables validation of the server certificate.no
min_versionstringMinimum acceptable TLS version.no

When min_version is not provided, the minimum acceptable TLS version is inherited from Go’s default minimum version, TLS 1.2. If min_version is provided, it must be set to one of the following strings:

  • "TLS10" (TLS 1.0)
  • "TLS11" (TLS 1.1)
  • "TLS12" (TLS 1.2)
  • "TLS13" (TLS 1.3)

Exported fields

The following fields are exported and can be referenced by other components:

NameTypeDescription
targetslist(map(string))The set of targets discovered from the docker API.

Each target includes the following labels:

  • __meta_docker_container_id: ID of the container.
  • __meta_docker_container_name: Name of the container.
  • __meta_docker_container_network_mode: Network mode of the container.
  • __meta_docker_container_label_<labelname>: Each label from the container.
  • __meta_docker_network_id: ID of the Docker network the container is in.
  • __meta_docker_network_name: Name of the Docker network the container is in.
  • __meta_docker_network_ingress: Set to true if the Docker network is an ingress network.
  • __meta_docker_network_internal: Set to true if the Docker network is an internal network.
  • __meta_docker_network_label_<labelname>: Each label from the network the container is in.
  • __meta_docker_network_scope: The scope of the network the container is in.
  • __meta_docker_network_ip: The IP of the container in the network.
  • __meta_docker_port_private: The private port on the container.
  • __meta_docker_port_public: The publicly exposed port from the container, if a port mapping exists.
  • __meta_docker_port_public_ip: The public IP of the container, if a port mapping exists.

Each discovered container maps to one target per unique combination of networks and port mappings used by the container.

Component health

discovery.docker is only reported as unhealthy when given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

discovery.docker does not expose any component-specific debug information.

Debug metrics

discovery.docker does not expose any component-specific debug metrics.

Examples

Linux or macOS hosts

This example discovers Docker containers when the host machine is macOS or Linux:

river 
discovery.docker "containers" {
  host = "unix:///var/run/docker.sock"
}

Windows hosts

This example discovers Docker containers when the host machine is Windows:

river 
discovery.docker "containers" {
  host = "tcp://localhost:2375"
}

NOTE: This example requires the “Expose daemon on tcp://localhost:2375 without TLS” setting to be enabled in the Docker Engine settings.