Manage Tailscale resources using Terraform

Terraform is an infrastructure as code tool that allows you to deploy infrastructure programmatically.

The Tailscale Terraform provider is maintained and published in the Terraform registry by Tailscale. We recommend using the latest version of the provider.

Features

Use the Terraform provider for Tailscale to:

Define your tailnet 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
- enabling or disabling 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:
- approving the device, using the tailscale_device_authorization resource
- disabling key expiry, using the tailscale_device_key resource
- setting tags, using the tailscale_device_tags resource
- advertising 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. We strongly recommend that you use an OAuth client because an OAuth client:

is associated with the tailnet, not an individual user
does not expire
supports scopes

For details, see OAuth clients.

Also specify your tailnet in the Tailscale Terraform provider configuration. For this value, you can provide a dash (-) to reference the default tailnet of the OAuth client ID and secret (or API access token) being used as credentials. This 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 and/or secrets manager.

Use the default variables OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, and TAILSCALE_TAILNET to provide your credentials and tailnet organization name to the Tailscale Terraform provider. Alternatively, see the Terraform topic Set 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 OAUTH_CLIENT_ID and 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 ‘`oauth_client_id`’ and ‘`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`
`oauth_client_id` (String)	The OAuth application’s ID when using OAuth client credentials. Both ‘`oauth_client_id`’ and ‘`oauth_client_secret`’ must be set. Conflicts with ‘`api_key`’.	`OAUTH_CLIENT_ID`
`oauth_client_secret` (String, Sensitive)	The OAuth application’s secret when using OAuth client credentials. Both ‘`oauth_client_id`’ and ‘`oauth_client_secret`’ must be set. Conflicts with ‘`api_key`’.	`OAUTH_CLIENT_SECRET`
`tailnet` (String)	The organization name of the tailnet to perform actions in.	`TAILSCALE_TAILNET`

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