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).
• File-based secret alternatives:
  • TAILSCALESD_BEARER_TOKEN_FILE
  • TAILSCALESD_CLIENT_ID_FILE
  • TAILSCALESD_CLIENT_SECRET_FILE

For systemd services, prefer LoadCredential= plus %d (runtime CREDENTIALS_DIRECTORY) and set TAILSCALESD_*_FILE values to files under %d.

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>.