Tailscale Provider

Installation

The Tailscale provider is available as a package in all Pulumi languages:

• JavaScript/TypeScript: @pulumi/tailscale
• Python: pulumi-tailscale
• Go: github.com/pulumi/pulumi-tailscale/sdk/go/tailscale
• .NET: Pulumi.Tailscale
• Java: com.pulumi/tailscale

Overview

This provider is used to interact with resources supported by the Tailscale API.

Use the navigation to the left to read about the available resources and functions.

Authentication

There are several ways to authenticate the Tailscale provider with the Tailscale API.

Using a trust credential (an OAuth client or federated identity) is recommended whenever possible as trust credentials can have granular access scopes applied to them whereas API keys cannot.

Available authentication methods are detailed below.

OAuth clients

OAuth clients can be used for authentication by setting the oauthClientId and oauthClientSecret arguments in the provider configuration to the client ID and client secret of a configured OAuth client respectively:

# Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
    tailscale:oauthClientId:
        value: my_client_id
    tailscale:oauthClientSecret:
        value: my_client_secret
    tailscale:tailnet:
        value: example.com

See argument reference for more details.

Federated identities

Workload identity federation can be used for authentication by setting the oauthClientId and identityToken in the provider configuration to the client ID of a configured federated identity and a JWT identity token from a compatible issuer respectively:

# Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
    tailscale:identityToken:
        value: my_identity_token
    tailscale:oauthClientId:
        value: my_client_id
    tailscale:tailnet:
        value: example.com

If Pulumi is running in a supported runtime (GitHub Actions, AWS via EC2 instance profile or ECS task role, or Google Cloud), the provider can discover the OIDC token from the runtime automatically. Configure only the oauthClientId and the audience expected by the federated identity:

# Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
    tailscale:audience:
        value: my_audience
    tailscale:oauthClientId:
        value: my_client_id
    tailscale:tailnet:
        value: example.com

For GitHub Actions, the workflow must declare permissions: id-token: write. For AWS, the runtime must have valid AWS credentials available. For GCP, the runtime must be able to reach the metadata server.

See argument reference for more details.

API keys

API keys can be used for authentication by setting the apiKey argument in the provider configuration:

# Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
    tailscale:apiKey:
        value: my_api_key
    tailscale:tailnet:
        value: example.com

See argument reference for more details.

Configuration Reference

• apiKey (String, Sensitive) The API key to use for authenticating requests to the API. Can be set via the TAILSCALE_API_KEY environment variable. If the value starts with ‘file:’ then it is treated as a path to a file on disk that contains the API key. Conflicts with ‘oauth_client_id’ and ‘oauth_client_secret’.
• audience (String) The OIDC audience to request when discovering an identity token from the runtime (GitHub Actions, AWS, or GCP) for workload identity federation. Can be set via the TAILSCALE_AUDIENCE environment variable. If the value starts with ‘file:’ then it is treated as a path to a file on disk that contains the audience. Requires ‘oauth_client_id’. Conflicts with ‘api_key’, ‘oauth_client_secret’, ‘identity_token’, and ‘identity_token_environment_variable_name’.
• baseUrl (String) The base URL of the Tailscale API. Defaults to https://api.tailscale.com. Can be set via the TAILSCALE_BASE_URL environment variable.
• identityToken (String, Sensitive) The jwt identity token to exchange for a Tailscale API token when using a federated identity. Can be set via the TAILSCALE_IDENTITY_TOKEN environment variable. If the value starts with ‘file:’ then it is treated as a path to a file on disk that contains the identity token. Conflicts with ‘api_key’, ‘oauth_client_secret’, and ‘identity_token_environment_variable_name’.
• identityTokenEnvironmentVariableName (String) The name of an environment variable to read the identity token from. This is useful when the identity token is provided by an external system (such as Pulumi Cloud workload identity) in an environment variable you do not control. If the resolved value of the environment variable starts with ‘file:’ then it is treated as a path to a file on disk that contains identity token. Conflicts with ‘identity_token’.
• oauthClientId (String) The OAuth application or federated identity’s ID when using OAuth client credentials or workload identity federation. Can be set via the TAILSCALE_OAUTH_CLIENT_ID environment variable. If the value starts with ‘file:’ then it is treated as a path to a file on disk that contains the client ID. Either ‘oauth_client_secret’ or ‘identity_token’ must be set alongside ‘oauth_client_id’. Conflicts with ‘api_key’.
• oauthClientSecret (String, Sensitive) The OAuth application’s secret when using OAuth client credentials. Can be set via the TAILSCALE_OAUTH_CLIENT_SECRET environment variable. If the value starts with ‘file:’ then it is treated as a path to a file on disk that contains the client secret. Conflicts with ‘api_key’ and ‘identity_token’.
• scopes (List of String) The OAuth 2.0 scopes to request when generating the access token using the supplied OAuth client credentials. See https://tailscale.com/kb/1623/trust-credentials#scopes for available scopes. Only valid when both ‘oauth_client_id’ and ‘oauth_client_secret’, or both are set.
• tailnet (String) The tailnet ID. Tailnets created before Oct 2025 can still use the legacy ID, but the Tailnet ID is the preferred identifier. Can be set via the TAILSCALE_TAILNET environment variable. Default is the tailnet that owns API credentials passed to the provider.
• userAgent (String) User-Agent header for API requests.