tailscale.md

Tailscale

Connect Namespace workloads to your Tailscale tailnet with workload identity federation.

NOTE
Tailscale integration is currently supported for Linux workloads only.

Namespace relies on workload identity federation to connect your workloads to your Tailscale tailnet. To get started, you need a Tailscale OIDC client ID and the set of tags that Namespace workloads should advertise when they register.

At runtime, Namespace issues a short-lived OpenID Connect ID token and uses it to register the workload with your tailnet. No long-lived Tailscale auth key or client secret needs to be stored in Namespace.

Configure Tailscale

Use the Tailscale admin console to create the client ID that Namespace will store.

1. Create an OpenID Connect trust credential

Open Tailscale's Trust credentials page, select Credential, then choose OpenID Connect.

2. Configure Namespace as the issuer

Configure the credential to trust Namespace's OIDC issuer:

The subject pattern above allows workloads from one Namespace workspace to join your tailnet. Namespace issues ID tokens with subjects in the form <workspace-id>/<instance-id> for workloads.

You can find your workspace ID in Workspace settings.

3. Grant node-registration access and tags

Grant the credential the ability to register nodes and select the tags that Namespace workloads are allowed to advertise. The tags you save in Namespace must be a subset of the tags allowed here.

For Namespace-managed node registration, enable the scope that allows auth key generation for node joins:

After you generate the credential, Tailscale shows both a Client ID and an Audience. Namespace only needs the Client ID. It automatically requests an ID token with audience api.tailscale.com/<client-id>.

Configure the integration in Namespace

Once you have the Tailscale client ID, store it in your Namespace workspace with a friendly name.

You can do this from the Integrations page in the Namespace console, or with the CLI:

echo 'nsc integrations tailscale set corp --oauth-client-id <tailscale-client-id> --tag tag:namespace --tag tag:ci'

This command creates or replaces the named spec corp. The stored tags are the tags Namespace passes to tailscale up --advertise-tags=... when the workload joins your tailnet.

You can pass tags either multiple times or as a comma-separated list:

echo 'nsc integrations tailscale set corp \
  --oauth-client-id <tailscale-client-id> \
  --tag tag:namespace,tag:ci'

Magic DNS

You can enable Tailscale Magic DNS so that workloads can reach other devices on your tailnet by their machine name. To enable it, pass the --enable-magic-dns flag:

echo 'nsc integrations tailscale set corp \
  --oauth-client-id <tailscale-client-id> \
  --tag tag:namespace \
  --enable-magic-dns'

You can also toggle Magic DNS directly from the Integrations page. To test that Magic DNS is working correctly you can perform a DNS lookup:

dig +search +short <device-name>

Inspect And Remove Specs

List the currently configured Tailscale specs in your workspace:

echo 'nsc integrations tailscale list'

To inspect the full machine-readable response instead, use JSON output:

echo 'nsc integrations tailscale list --output json'

Remove a named spec when you no longer need it:

echo 'nsc integrations tailscale remove corp'

How Namespace Uses The Spec

When a Namespace workload uses one of these named specs, Namespace resolves the saved client ID and tags, issues a short-lived ID token from https://federation.namespaceapis.com, and joins Tailscale with:

echo 'tailscale up \
  --client-id="<tailscale-client-id>?preauthorized=true&ephemeral=true" \
  --id-token="$ID_TOKEN" \
  --advertise-tags=tag:namespace,tag:ci'

This means:

Use with GitHub Actions

You can connect your CI runners to your Tailscale tailnet by adding the tailscale.spec feature to your runner configuration. This lets your GitHub Actions workflows access private services on your tailnet (e.g. databases, staging environments, internal APIs).

With runner profiles

Append the tailscale.spec feature to your profile name:

runs-on:
  - namespace-profile-my-profile;tailscale.spec=corp

With runner labels

Add the tailscale.spec feature to the namespace-features label:

runs-on:
  - nscloud-ubuntu-22.04-amd64-4x16-with-features
  - namespace-features:tailscale.spec=corp

The runner will automatically join your tailnet before the workflow job starts. Replace corp with the name of the Tailscale spec you created with nsc integrations tailscale set.

See Connecting to Tailscale for how this feature fits alongside other runner settings.

Use with Devboxes

Devboxes support Tailscale out of the box. You can enable it in two ways:

g
integrations:
  tailscale:
    spec: corp

See the spec file reference for the full configuration reference.

Notes