Tailscale

View as Markdown

Community Platform

runZero integrates with Tailscale to import the devices in your tailnet, including their addresses, operating system, hostnames, tags, and the Tailscale account that owns each node. Tailscale is the first integration runZero ships as a platform-packaged Starlark integration: it is built with the same engine as custom integration scripts, but the script is embedded in the product, so it configures like any other connector — no script editing involved.

Getting started

To set up the Tailscale integration, you’ll need to:

  1. Create a Tailscale API access token, or an OAuth client, in the Tailscale admin console.
  2. Add the Tailscale credential to runZero.
  3. Set up and activate the connector task to sync your data with runZero.

Requirements

  • Access to the Tailscale admin console with permission to create API access tokens or OAuth clients.
  • The runZero custom integrations entitlement.
  • When the task runs on an Explorer, the Explorer must be version 5.0.260723.0 or newer. The Tailscale API is reachable from the cloud, so the task can also run without an Explorer.

Step 1: Create a Tailscale API token or OAuth client

The integration accepts either credential form:

  • API access token — in the Tailscale admin console, go to Settings > Keys and generate an API access token (it starts with tskey-api-). Tokens expire, so prefer an OAuth client for a scheduled sync.
  • OAuth client — in the Tailscale admin console, go to Settings > OAuth clients and create a client with at least the devices:core:read scope. Note the client ID and client secret.

Step 2: Add the Tailscale credential to runZero

  1. Go to the Credentials page in runZero and click Add Credential.
  2. Choose Tailscale Settings & Secrets from the list of credential types.
  3. Provide the following information:
    • Tailscale API URL — leave the default https://api.tailscale.com unless you proxy the API.
    • Tailnet — the tailnet ID or name, for example T1234CNTRL or example.com.
    • OAuth client ID — the OAuth client ID, or leave blank to use a plain API key.
    • API key / OAuth client secret — the API access token, or the OAuth client secret when a client ID is set.
  4. Save the credential.

Step 3: Set up and activate the Tailscale integration

  1. Activate a connection to Tailscale. You can also reach it from the Tailscale card on the integrations page.
  2. Choose the credential you added earlier. If you don’t see the credential listed, make sure the credential has access to the organization you are currently in.
  3. Enter a name for the task, like Tailscale sync.
  4. Schedule the sync, and choose the site newly discovered assets should be created in.
  5. To keep the sync from creating assets runZero has not seen through other means, enable Exclude assets that cannot be merged into an existing asset.
  6. Select an Explorer, or leave the selection empty to run the sync from the runZero cloud.
  7. Activate the connection. The sync will run on the defined schedule.

Step 4: View Tailscale assets

After a successful sync, your Tailscale devices appear in your inventory with the Tailscale icon in the Source column, and their attributes are stored under tailscale.device.*. The Tailscale account that owns each node is resolved into asset ownership.

To filter by Tailscale assets:

source:tailscale
Updated