Manage Tailscale resources using Terraform

Last validated: Jan 30, 2026

Terraform is an infrastructure as code (IaC) tool that lets you deploy infrastructure programmatically. Tailscale maintains the Tailscale Terraform provider in the Terraform registry by Tailscale. We recommend using the latest version of the provider.

You can use the Tailscale Terraform provider to:

Define your policy file using the tailscale_acl resource.
Set DNS settings, including:
- Global nameservers using the tailscale_dns_nameservers resource.
- Restricted nameservers for split DNS, using the tailscale_dns_search_paths resource.
- MagicDNS using the tailscale_dns_preferences resource.
Generate an auth key (including setting whether it's reusable, ephemeral, pre-authorized, and tagged) using the tailscale_key resource.
Manage properties of a device, including:
- Device approval using the tailscale_device_authorization resource.
- Key expiry using the tailscale_device_key resource.
- Tags using the tailscale_device_tags resource.
- Subnet routes using the tailscale_device_subnet_routes resource.

Refer to the Terraform Provider documentation for the full list of supported resources.

Credentials and tailnet configuration

To use Terraform with Tailscale, configure the Tailscale Terraform provider with your Tailscale credentials, which can be a trust credential or an API access token.

Tailscale recommend that you use a trust credential (an OAuth client or federated identity) because trust credentials are associated with the tailnet, not an individual user, do not expire, and support scopes. For details, refer to trust credentials.

You must also specify your tailnet in the Tailscale Terraform provider configuration. You can provide a dash (-) to reference the default tailnet of the trust credential (or API access token) used as credentials. Using the default tailnet from the credential information is the best option for most users. Alternatively, you can specify your tailnet ID. You can find your tailnet ID in the General page of the admin console.

It is not recommended to store sensitive information, such as an OAuth client or API access token, in source control. Instead, use an environment variable or a secrets manager.

Use the default variables TAILSCALE_OAUTH_CLIENT_ID, TAILSCALE_OAUTH_CLIENT_SECRET, and TAILSCALE_TAILNET to provide your credentials and tailnet organization name to the Tailscale Terraform provider. Alternatively, refer to the Terraform documentation for setting values with variables.

If you are using a federated identity instead of an OAuth client, use the default TAILSCALE_IDENTITY_TOKEN variable instead of TAILSCALE_OAUTH_CLIENT_SECRET.

If you are using an API access token instead of an OAuth client, use the default TAILSCALE_API_KEY variable instead of TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET.

Environment variables

You can store most information as environment variables in Terraform. Tailscale uses environment variables for the following configuration settings:

Setting	Description	Environment variable
`api_key` (String, Sensitive)	The API key to use for authenticating requests to the API. Conflicts with '`TAILSCALE_OAUTH_CLIENT_ID`' and '`TAILSCALE_OAUTH_CLIENT_SECRET`'.	`TAILSCALE_API_KEY`
`base_url` (String)	The base URL of the Tailscale API. Defaults to `https://api.tailscale.com`.	`TAILSCALE_BASE_URL`
`TAILSCALE_OAUTH_CLIENT_ID` (String)	The OAuth application or federated identity's ID when using OAuth client credentials or workload identity federation. If set, then either '`TAILSCALE_OAUTH_CLIENT_SECRET`' or '`TAILSCALE_IDENTITY_TOKEN`' must also be set, but not both. Conflicts with '`api_key`'.	`TAILSCALE_OAUTH_CLIENT_ID`
`TAILSCALE_OAUTH_CLIENT_SECRET` (String, Sensitive)	The OAuth application's secret when using OAuth client credentials. If set, '`TAILSCALE_OAUTH_CLIENT_ID`' must also be set. Conflicts with '`api_key`' and '`identity_token`'.	`TAILSCALE_OAUTH_CLIENT_SECRET`
`TAILSCALE_IDENTITY_TOKEN` (String, Sensitive)	The JWT identity token to exchange for a Tailscale API token when using a federated identity. Conflicts with '`api_key`' and '`client_secret`'.	`TAILSCALE_OAUTH_CLIENT_SECRET`
`tailnet` (String)	The tailnet ID to perform actions in.	`TAILSCALE_TAILNET`

Migrate from the community-contributed Terraform provider

If you previously used the community-contributed Terraform provider, and now want to use the provider managed and published by Tailscale, update the source argument in your Terraform configuration. That is, update source = "davidsbond/tailscale" to source = "tailscale/tailscale".

Special thanks

Special thanks to David Bond, who contributed and maintained the original community-contributed Tailscale Terraform provider. Tailscale now maintains and publishes this provider.

Support

The Tailscale Terraform provider is maintained and published in the Terraform registry by Tailscale. If you have an issue or feature request, contact support or file a GitHub issue.