Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cfunkhouser/tailscalesd

Prometheus Service Discovery for Tailscale
https://github.com/cfunkhouser/tailscalesd

Last synced: 2 months ago
JSON representation

Prometheus Service Discovery for Tailscale

Awesome Lists containing this project

README 

        
# 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:



## 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](https://github.com/cfunkhouser/tailscalesd/releases/latest).



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 to `0.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 the

  `tailscaled`-exported local API for discovery.

- `-localapi_socket` / `TAILSCALE_LOCAL_API_SOCKET` is the path to the Unix

  domain socket over which `tailscaled` 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`



```console

$ 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`](./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`](./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:



Possible target labels follow. See the label comments in

[`tailscalesd.go`](./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.



```yaml

---

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.



```yaml

---

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__

```