Manage Tailscale resources using Terraform

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 ACLs 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.

Credentials and tailnet configuration

To use Terraform with Tailscale, configure the Tailscale Terraform provider with your Tailscale credentials, which can be an OAuth client ID and secret or an API access token.

Tailscale recommend that you use an OAuth client because an OAuth client is associated with the tailnet, not an individual user, does not expire, and supports scopes. For details, refer to OAuth clients.

You must also specify your tailnet in the Tailscale Terraform provider configuration. You can provide a dash (-) to reference the default tailnet of the OAuth client ID and secret (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 organization name, which you can find in the General settings 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 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's ID when using OAuth client credentials. Both '`TAILSCALE_OAUTH_CLIENT_ID`' and '`TAILSCALE_OAUTH_CLIENT_SECRET`' must be set. Conflicts with '`api_key`'.	`TAILSCALE_OAUTH_CLIENT_ID`
`TAILSCALE_OAUTH_CLIENT_SECRET` (String, Sensitive)	The OAuth application's secret when using OAuth client credentials. Both '`TAILSCALE_OAUTH_CLIENT_ID`' and '`TAILSCALE_OAUTH_CLIENT_SECRET`' must be set. Conflicts with '`api_key`'.	`TAILSCALE_OAUTH_CLIENT_SECRET`
`tailnet` (String)	The organization name of the tailnet 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.