130 lines
4.6 KiB
Markdown
130 lines
4.6 KiB
Markdown
# 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][0] for more information on the HTTP service discovery format.
|
|
|
|
[0]: https://prometheus.io/docs/prometheus/latest/http_sd/
|
|
|
|
## Example
|
|
|
|
`curl -H "Authorization: Bearer supersecret" http://tailscalesd:9242`
|
|
|
|
``` json
|
|
[
|
|
{
|
|
"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: https://gitlab.com/guardianproject-ops/tailscalesd/container_registry/5749401
|
|
|
|
``` shell
|
|
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`):
|
|
|
|
```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](https://github.com/trallnag/prometheus-fastapi-instrumentator)
|
|
|
|
## Dev
|
|
|
|
### Running the Application
|
|
|
|
1. **Install Dependencies**: Ensure that all required dependencies are installed.
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
uv run tailscalesd
|
|
```
|
|
|
|
4. **Access the Application**: The application will be accessible at `http://<host>:<port>`.
|