--- title: "discovery.dockerswarm | Grafana Agent documentation" description: "Learn about discovery.dockerswarm" --- # discovery.dockerswarm `discovery.dockerswarm` allows you to retrieve scrape targets from [Docker Swarm](https://docs.docker.com/engine/swarm/key-concepts/). ## Usage Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy discovery.dockerswarm "LABEL" { host = "DOCKER_DAEMON_HOST" role = "SWARM_ROLE" } ``` ## Arguments The following arguments are supported: Expand table | Name | Type | Description | Default | Required | |--------------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------|---------|----------| | `host` | `string` | Address of the Docker daemon. | | yes | | `role` | `string` | Role of the targets to retrieve. Must be `services`, `tasks`, or `nodes`. | | yes | | `port` | `number` | The port to scrape metrics from, when `role` is nodes, and for discovered tasks and services that don’t have published ports. | `80` | no | | `refresh_interval` | `duration` | Interval at which to refresh the list of targets. | `"60s"` | no | | `bearer_token_file` | `string` | File containing a bearer token to authenticate with. | | no | | `bearer_token` | `secret` | Bearer token to authenticate with. | | no | | `enable_http2` | `bool` | Whether HTTP2 is supported for requests. | `true` | no | | `follow_redirects` | `bool` | Whether redirects returned by the server should be followed. | `true` | no | | `proxy_url` | `string` | HTTP proxy to send requests through. | | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no | At most, one of the following can be provided: - [`bearer_token` argument](#arguments). - [`bearer_token_file` argument](#arguments). - [`basic_auth` block](#basic_auth-block). - [`authorization` block](#authorization-block). - [`oauth2` block](#oauth2-block). `no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured. `proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured. `proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured. ## Blocks The following blocks are supported inside the definition of `discovery.dockerswarm`: Expand table | Hierarchy | Block | Description | Required | |-------------------------|---------------------------------------|------------------------------------------------------------------------------------|----------| | filter | [filter](#filter-block) | Optional filter to limit the discovery process to a subset of available resources. | no | | basic\_auth | [basic\_auth](#basic_auth-block) | Configure basic\_auth for authenticating to the endpoint. | no | | authorization | [authorization](#authorization-block) | Configure generic authorization to the endpoint. | no | | oauth2 | [oauth2](#oauth2-block) | Configure OAuth2 for authenticating to the endpoint. | no | | oauth2 > tls\_config | [tls\_config](#tls_config-block) | Configure TLS settings for connecting to the endpoint. | no | | tls\_config | [tls\_config](#tls_config-block) | Configure TLS settings for connecting to the endpoint. | no | The `>` symbol indicates deeper levels of nesting. For example, `oauth2 > tls_config` refers to a `tls_config` block defined inside an `oauth2` block. ### filter block Filters can be used to limit the discovery process to a subset of available resources. It is possible to define multiple `filter` blocks within the `discovery.dockerswarm` block. The list of available filters depends on the `role`: - [services filters](https://docs.docker.com/engine/api/v1.40/#operation/ServiceList) - [tasks filters](https://docs.docker.com/engine/api/v1.40/#operation/TaskList) - [nodes filters](https://docs.docker.com/engine/api/v1.40/#operation/NodeList) The following arguments can be used to configure a filter. Expand table | Name | Type | Description | Default | Required | |----------|----------------|--------------------------------------------|---------|----------| | `name` | `string` | Name of the filter. | | yes | | `values` | `list(string)` | List of values associated with the filter. | | yes | ### basic\_auth block Expand table | Name | Type | Description | Default | Required | |-----------------|----------|------------------------------------------|---------|----------| | `password_file` | `string` | File containing the basic auth password. | | no | | `password` | `secret` | Basic auth password. | | no | | `username` | `string` | Basic auth username. | | no | `password` and `password_file` are mutually exclusive, and only one can be provided inside a `basic_auth` block. ### authorization block Expand table | Name | Type | Description | Default | Required | |--------------------|----------|--------------------------------------------|---------|----------| | `credentials_file` | `string` | File containing the secret value. | | no | | `credentials` | `secret` | Secret value. | | no | | `type` | `string` | Authorization type, for example, “Bearer”. | | no | `credential` and `credentials_file` are mutually exclusive, and only one can be provided inside an `authorization` block. ### oauth2 block Expand table | Name | Type | Description | Default | Required | |--------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------|----------| | `client_id` | `string` | OAuth2 client ID. | | no | | `client_secret_file` | `string` | File containing the OAuth2 client secret. | | no | | `client_secret` | `secret` | OAuth2 client secret. | | no | | `endpoint_params` | `map(string)` | Optional parameters to append to the token URL. | | no | | `proxy_url` | `string` | HTTP proxy to send requests through. | | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no | | `scopes` | `list(string)` | List of scopes to authenticate with. | | no | | `token_url` | `string` | URL to fetch the token from. | | no | `client_secret` and `client_secret_file` are mutually exclusive, and only one can be provided inside an `oauth2` block. The `oauth2` block may also contain a separate `tls_config` sub-block. `no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured. `proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured. `proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured. ### tls\_config block Expand table | Name | Type | Description | Default | Required | |------------------------|----------|----------------------------------------------------------|---------|----------| | `ca_pem` | `string` | CA PEM-encoded text to validate the server with. | | no | | `ca_file` | `string` | CA certificate to validate the server with. | | no | | `cert_pem` | `string` | Certificate PEM-encoded text for client authentication. | | no | | `cert_file` | `string` | Certificate file for client authentication. | | no | | `insecure_skip_verify` | `bool` | Disables validation of the server certificate. | | no | | `key_file` | `string` | Key file for client authentication. | | no | | `key_pem` | `secret` | Key PEM-encoded text for client authentication. | | no | | `min_version` | `string` | Minimum acceptable TLS version. | | no | | `server_name` | `string` | ServerName extension to indicate the name of the server. | | no | The following pairs of arguments are mutually exclusive and can’t both be set simultaneously: - `ca_pem` and `ca_file` - `cert_pem` and `cert_file` - `key_pem` and `key_file` When configuring client authentication, both the client certificate (using `cert_pem` or `cert_file`) and the client key (using `key_pem` or `key_file`) must be provided. 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: Expand table | Name | Type | Description | |-----------|---------------------|-------------------------------------------| | `targets` | `list(map(string))` | The set of targets discovered from Swarm. | ## Roles The `role` attribute decides the role of the targets to retrieve. ### services The `services` role discovers all [Swarm services](https://docs.docker.com/engine/swarm/key-concepts/#services-and-tasks) and exposes their ports as targets. For each published port of a service, a single target is generated. If a service has no published ports, a target per service is created using the `port` attribute defined in the arguments. Available meta labels: - `__meta_dockerswarm_service_id`: the ID of the service. - `__meta_dockerswarm_service_name`: the name of the service. - `__meta_dockerswarm_service_mode`: the mode of the service. - `__meta_dockerswarm_service_endpoint_port_name`: the name of the endpoint port, if available. - `__meta_dockerswarm_service_endpoint_port_publish_mode`: the publish mode of the endpoint port. - `__meta_dockerswarm_service_label_`: each label of the service. - `__meta_dockerswarm_service_task_container_hostname`: the container hostname of the target, if available. - `__meta_dockerswarm_service_task_container_image`: the container image of the target. - `__meta_dockerswarm_service_updating_status`: the status of the service, if available. - `__meta_dockerswarm_network_id`: the ID of the network. - `__meta_dockerswarm_network_name`: the name of the network. - `__meta_dockerswarm_network_ingress`: whether the network is ingress. - `__meta_dockerswarm_network_internal`: whether the network is internal. - `__meta_dockerswarm_network_label_`: each label of the network. - `__meta_dockerswarm_network_scope`: the scope of the network. ### tasks The `tasks` role discovers all [Swarm tasks](https://docs.docker.com/engine/swarm/key-concepts/#services-and-tasks) and exposes their ports as targets. For each published port of a task, a single target is generated. If a task has no published ports, a target per task is created using the `port` attribute defined in the arguments. Available meta labels: - `__meta_dockerswarm_container_label_`: each label of the container. - `__meta_dockerswarm_task_id`: the ID of the task. - `__meta_dockerswarm_task_container_id`: the container ID of the task. - `__meta_dockerswarm_task_desired_state`: the desired state of the task. - `__meta_dockerswarm_task_slot`: the slot of the task. - `__meta_dockerswarm_task_state`: the state of the task. - `__meta_dockerswarm_task_port_publish_mode`: the publish mode of the task port. - `__meta_dockerswarm_service_id`: the ID of the service. - `__meta_dockerswarm_service_name`: the name of the service. - `__meta_dockerswarm_service_mode`: the mode of the service. - `__meta_dockerswarm_service_label_`: each label of the service. - `__meta_dockerswarm_network_id`: the ID of the network. - `__meta_dockerswarm_network_name`: the name of the network. - `__meta_dockerswarm_network_ingress`: whether the network is ingress. - `__meta_dockerswarm_network_internal`: whether the network is internal. - `__meta_dockerswarm_network_label_`: each label of the network. - `__meta_dockerswarm_network_label`: each label of the network. - `__meta_dockerswarm_network_scope`: the scope of the network. - `__meta_dockerswarm_node_id`: the ID of the node. - `__meta_dockerswarm_node_hostname`: the hostname of the node. - `__meta_dockerswarm_node_address`: the address of the node. - `__meta_dockerswarm_node_availability`: the availability of the node. - `__meta_dockerswarm_node_label_`: each label of the node. - `__meta_dockerswarm_node_platform_architecture`: the architecture of the node. - `__meta_dockerswarm_node_platform_os`: the operating system of the node. - `__meta_dockerswarm_node_role`: the role of the node. - `__meta_dockerswarm_node_status`: the status of the node. The `__meta_dockerswarm_network_*` meta labels are not populated for ports which are published with mode=host. ### nodes The `nodes` role is used to discover [Swarm nodes](https://docs.docker.com/engine/swarm/key-concepts/#nodes). Available meta labels: - `__meta_dockerswarm_node_address`: the address of the node. - `__meta_dockerswarm_node_availability`: the availability of the node. - `__meta_dockerswarm_node_engine_version`: the version of the node engine. - `__meta_dockerswarm_node_hostname`: the hostname of the node. - `__meta_dockerswarm_node_id`: the ID of the node. - `__meta_dockerswarm_node_label_`: each label of the node. - `__meta_dockerswarm_node_manager_address`: the address of the manager component of the node. - `__meta_dockerswarm_node_manager_leader`: the leadership status of the manager component of the node (true or false). - `__meta_dockerswarm_node_manager_reachability`: the reachability of the manager component of the node. - `__meta_dockerswarm_node_platform_architecture`: the architecture of the node. - `__meta_dockerswarm_node_platform_os`: the operating system of the node. - `__meta_dockerswarm_node_role`: the role of the node. - `__meta_dockerswarm_node_status`: the status of the node. ## Component health `discovery.dockerswarm` is only reported as unhealthy when given an invalid configuration. In those cases, exported fields retain their last healthy values. ## Debug information `discovery.dockerswarm` does not expose any component-specific debug information. ## Debug metrics `discovery.dockerswarm` does not expose any component-specific debug metrics. ## Example This example discovers targets from Docker Swarm tasks: Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy discovery.dockerswarm "example" { host = "unix:///var/run/docker.sock" role = "tasks" filter { name = "id" values = ["0kzzo1i0y4jz6027t0k7aezc7"] } filter { name = "desired-state" values = ["running", "accepted"] } } prometheus.scrape "demo" { targets = discovery.dockerswarm.example.targets forward_to = [prometheus.remote_write.demo.receiver] } prometheus.remote_write "demo" { endpoint { url = PROMETHEUS_REMOTE_WRITE_URL basic_auth { username = USERNAME password = PASSWORD } } } ``` Replace the following: - `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote\_write-compatible server to send metrics to. - `USERNAME`: The username to use for authentication to the remote\_write API. - `PASSWORD`: The password to use for authentication to the remote\_write API. ## Compatible components `discovery.dockerswarm` has exports that can be consumed by the following components: - Components that consume [Targets](../../compatibility/#targets-consumers) > Note > > Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.