tailscalesd

Service discovery for tailscale

Returns a list of services for Prometheus to scrape, with some extra smarts for Guardian Project Ops.

See the prometheus docs for more information on the HTTP service discovery format.

Example

curl -H "Authorization: Bearer supersecret" http://tailscalesd:9242

[
  {
    "labels": {
      "__meta_tailscale_device_client_version": "1.52.1-t75d3c9385-g3e9627f3b",
      "__meta_tailscale_device_hostname": "gp-ourapp-prod-main",
      "__meta_tailscale_device_authorized": "true",
      "__meta_tailscale_device_id": "1234678910",
      "__meta_tailscale_device_name": "gp-ourapp-prod-main.rocky-rocks.ts.net",
      "__meta_tailscale_device_os": "linux",
      "__meta_tailscale_tailnet": "ourtailnet"
    },
    "targets": [
      "100.100.100.101"
    ]
  },
  {
    "labels": {
      "__meta_tailscale_device_client_version": "1.52.1-t75d3c9385-g3e9627f3b",
      "__meta_tailscale_device_hostname": "ip-10-10-10-10",
      "__meta_tailscale_device_authorized": "true",
      "__meta_tailscale_device_id": "123456789101",
      "__meta_tailscale_device_name": "ip-10-31-0-182.rocky-rocks.ts.net",
      "__meta_tailscale_device_os": "linux",
      "__meta_tailscale_tailnet": "ourtailnet"
    },
    "targets": [
      "100.100.100.102"
    ]
  }
]

Usage

Deploy with a container

• Container image: registry.gitlab.com/guardianproject-ops/tailscalesd:VERSION
• See versions at: 5749401

docker run \
--name=tailscalesd \
--rm \
--cap-drop=all \
--user 1000:1000 \
--publish 127.0.0.1:9242:9242 \
--env TAILSCALESD_ENV_FILE=/tailscalesd.env \
--mount type=bind,dst=/tailscalesd.env,ro=true,src=/path/to/tailscalesd.env \
registry.gitlab.com/guardianproject-ops/tailscalesd:latest

Configuration

Configuration values can be set using environment variables, or optionally loaded from an environment file. The settings include:

• host (TAILSCALESD_HOST): The host address on which the application will bind (designed to be used in a container, BE CAREFUL!). Default is 0.0.0.0.
• port (TAILSCALESD_PORT): The port number on which the application will be accessible. Default is 9242.
• interval (TAILSCALESD_INTERVAL): The interval on which the Tailscale API is polled in seconds. Default is 60.
• bearer_token (TAILSCALESD_BEARER_TOKEN): The authentication token passed in the Authorization header (required).
• tailnet (TAILSCALESD_TAILNET): The Tailscale tailnet identifier (required).
• client_id (TAILSCALESD_CLIENT_ID): The Tailscale oauth client id (required).
• client_secret (TAILSCALESD_CLIENT_SECRET): The Tailscale oauth client secret (required).

Environment File

You can also specify an environment file to load configuration values. The path to the environment file should be set in the TAILSCALESD_ENV_FILE environment variable. All of the config values can be provided in the env file.

Example Environment File (env):

TAILSCALESD_TAILNET=my-tailnet
TAILSCALESD_CLIENT_ID=xxxx
TAILSCALESD_CLIENT_SECRET=yyyyy
TAILSCALESD_HOST=127.0.0.1
TAILSCALESD_BEARER_TOKEN=supersecret

Monitoring

This service provides the following Prometheus metrics:

• tailscalesd_unhandled_background_task_crashes
  • Type: Counter
  • Description: The number of unhandled background task crashes. This counter increases every time a background task crashes without being handled by the application.
• tailscalesd_matrix_sd_down
  • Type: Counter
  • Description: The number times a matrix sd host was unreachable. This counter increments each time a connection attempt to a matrix sd host fails.
  • Labels:
    • device_hostname: The hostname of the device that was unreachable.
• tailscalesd_polling_up
  • Type: Gauge
  • Description: Indicates if tailscalesd can access the tailscale devices API up (1) or down (0)

It also provides HTTP server metrics from trallnag/prometheus-fastapi-instrumentator

Dev

Running the Application

1. Install Dependencies: Ensure that all required dependencies are installed.

   uv sync --all-groups
   

2. Set Configuration: Set the necessary environment variables or create an environment file with the configuration values.

3. Start the Application: Run the application using the following command:

   uv run tailscalesd
   

4. Access the Application: The application will be accessible at http://<host>:<port>.