tailscalesd
tailscalesd copied to clipboard
Prometheus Service Discovery for Tailscale
TailscaleSD - Prometheus Service Discovery for Tailscale
Serves Prometheus HTTP Service Discovery for devices on a Tailscale Tailnet.
For details on HTTP Service Discovery, read the Prometheus docs: https://prometheus.io/docs/prometheus/latest/http_sd/
Maintainer Updates
- 2023-12-23 Hey folks. For the past few years, I have held a job at which I did not use Tailscale (nor GitHub), and which made open source contributions onerous. I have left that job. Sorry for the sparse attention I've paid to this project. That should change a bit from now.
Installation
Release builds for various architectures can be obtained from GitHub.
There is also a
Docker image provided under ghcr.io/cfunkhouser/tailscalesd
. The latest
tag
is automatically updated with each release. The Docker image is available for
arm/v7
, arm64
and amd64
.
Usage
The tailscalesd
server is very simple. It serves the SD payload at /
on its
HTTP server. It respects the following configuration parameters, each of which
may be specified as a flag or an environment variable.
As of v0.2.1 the the local and public APIs are no longer mutually exclusive.
Setting the -localapi
flag and providing -tailnet
+ -token
will result in
a union of targets from both APIs.
-
-address
/ADDRESS
is the host:port on which to serve TailscaleSD. Defaults to0.0.0.0:9242
. -
-ipv6
/EXPOSE_IPV6
instructs TailscaleSD to include IPv6 addresses in the target list. Be careful with this, the colons in IPv6 addresses wreak havoc with Prometheus configurations! -
-localapi
/TAILSCALE_USE_LOCAL_API
instructs TailscaleSD to use thetailscaled
-exported local API for discovery. -
-localapi_socket
/TAILSCALE_LOCAL_API_SOCKET
is the path to the Unix domain socket over whichtailscaled
serves the local API. -
-poll
/TAILSCALE_API_POLL_LIMIT
is the limit of how frequently the Tailscale API may be polled. Cached results are served between intervals. Defaults to 5 minutes. Also applies to local API. -
-tailnet
/TAILNET
is the name of the tailnet to enumerate. Required when using the public API. -
-token
/TAILSCALE_API_TOKEN
is a Tailscale API token with appropriate permissions to access the Tailscale API and enumerate devices. Required when using the public API. -
-client_id
/TAILSCALE_CLIENT_ID
is an OAuth Client ID that can be used to get scoped Tailscale API access, and needn't be as short-lived as Tailscale API tokens. It must be used with-client_secret
. -
-client_secret
/TAILSCALE_CLIENT_SECRET
is an OAuth Client Secret that can be used to get scoped Tailscale API access, and needn't be as short-lived as Tailscale API tokens. It must be used with-client_id
$ TAILSCALE_API_TOKEN=SUPERSECRET tailscalesd --tailnet [email protected]
2021-08-04T15:38:14Z Serving Tailscale service discovery on "0.0.0.0:9242"
Public vs Local API
TailscaleSD is capable of discovering devices both from Tailscale's public API,
and from the local API served by tailscaled
on the node on which TailscaleSD
is run. By using the public API, TailscaleSD will dicover all devices in the
tailnet, regardless of whether the local node is able to reach them or not.
Devices found using the local API will be reachable from the local node,
according to your Tailscale ACLs.
See the label comments in tailscalesd.go
for details about
which labels are supported for each API type. Do not assume they will be the
same labels, or that values will match across the APIs!
Metrics
As of v0.2.1, TailscaleSD exports Prometheus metrics on the standard /metrics
endpoint. In addition to the standard Go metrics, you will find
TailscaleSD-specific metrics defined in metrics.go
. The
metrics are targetted at understanding the behavior of TailscaleSD itself.
Contributions of additional interesting metrics are welcome, but please remember
that details about your devices should be handled by your monitoring. This is a
target discovery tool, not a Prometheus exporter for Tailscale!
Prometheus Configuration
Configure Prometheus by placing the tailscalesd
URL in a http_sd_configs
block in a scrape_config
. The following labels are potentially made available
for all Tailscale nodes discovered, however any label for which the Tailscale
API did not return a value will be omitted. For more details on each field and
the API in general, see:
https://github.com/tailscale/tailscale/blob/main/api.md#tailnet-devices-get
Possible target labels follow. See the label comments in
tailscalesd.go
for details. There will be one target entry
for each unique combination of all labels.
-
__meta_tailscale_api
-
__meta_tailscale_device_authorized
-
__meta_tailscale_device_client_version
-
__meta_tailscale_device_hostname
-
__meta_tailscale_device_id
-
__meta_tailscale_device_name
-
__meta_tailscale_device_os
-
__meta_tailscale_device_tag
-
__meta_tailscale_tailnet
Example: Pinging Tailscale Hosts
In the example below, Prometheus will discover Tailscale nodes and attempt to ping them using a blackbox exporter.
---
global:
scrape_interval: 1m
scrape_configs:
- job_name: tailscale-prober
metrics_path: /probe
params:
module: [icmp]
http_sd_configs:
- url: http://localhost:9242/
relabel_configs:
- source_labels: [__address__]
target_label: __param_target
- source_labels: [__param_target]
target_label: instance
- source_labels: [__meta_tailscale_device_hostname]
target_label: tailscale_hostname
- source_labels: [__meta_tailscale_device_name]
target_label: tailscale_name
- target_label: __address__
replacement: your.blackbox.exporter:9115
Example: Scraping Node Exporter from Tailscale Hosts
This example appends the node exporter port 9100
to the addresses returned
from the Tailscale API, and instructs Prometheus to collect those metrics. This
is likely to result in many "down" targets if your tailnet contains hosts
without the node exporter. It also doesn't play well with IPv6 addresses.
---
global:
scrape_interval: 1m
scrape_configs:
- job_name: tailscale-node-exporter
http_sd_configs:
- url: http://localhost:9242/
relabel_configs:
- source_labels: [__meta_tailscale_device_hostname]
target_label: tailscale_hostname
- source_labels: [__meta_tailscale_device_name]
target_label: tailscale_name
- source_labels: [__address__]
regex: '(.*)'
replacement: $1:9100
target_label: __address__