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
- global nameservers, using the
- 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
- approving the device, using the
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.
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.