terraform-provider-tailscale

This repository contains the source code for the Tailscale Terraform provider. This Terraform provider lets you interact with the Tailscale API.

See the documentation in the Terraform registry for the most up-to-date information and latest release.

This provider is maintained by Tailscale. Thanks to everyone who contributed to the development of the Tailscale Terraform provider, and special thanks to davidsbond.

Getting Started

To install this provider, copy and paste this code into your Terraform configuration. Then, run terraform init:

terraform {
  required_providers {
    tailscale = {
      source = "tailscale/tailscale"
      version = "~> 0.16" // Latest 0.16.x
    }
  }
}

provider "tailscale" {
  api_key = "tskey-api-..."
}

In the provider block, set your API key in the api_key field. Alternatively, use the TAILSCALE_API_KEY environment variable.

Using OAuth client

Instead of using a personal API key, you can configure the provider to use an OAuth client, e.g.:

provider "tailscale" {
  oauth_client_id = "..."
  oauth_client_secret = "tskey-client-..."
}

API endpoint

The default api endpoint is https://api.tailscale.com. If your coordination/control server API is at another endpoint, you can pass in base_url in the provider block.

provider "tailscale" {
  api_key = "tskey-api-..."
  base_url = "https://api.us.tailscale.com"
}

Updating an existing installation

To update an existing terraform deployment currently using the original davidsbond/tailscale provider, use:

terraform state replace-provider registry.terraform.io/davidsbond/tailscale registry.terraform.io/tailscale/tailscale

Contributing

Please review the contributing guidelines and code of conduct before contributing to this codebase. Please create a new issue for bugs and feature requests and fill in as much detail as you can.

Local Provider Development

The Terraform plugin documentation on debugging provides helpful strategies for debugging while developing plugins.

Namely, adding a development override for the tailscale/tailscale provider allows for using your local copy of the provider instead of a published version.

Your terraformrc should look something like the following:

provider_installation {
  # This disables the version and checksum verifications for this
  # provider and forces Terraform to look for the tailscale/tailscale
  # provider plugin in the given directory.
  dev_overrides {
    "tailscale/tailscale" = "/path/to/this/repo/on/disk"
  }
  # For all other providers, install them directly from their origin provider
  # registries as normal. If you omit this, Terraform will _only_ use
  # the dev_overrides block, and so no other providers will be available.
  direct {}
}

Acceptance Tests

Tests in this repo that are prefixed with TestAcc are acceptance tests which run against a real instance of the tailscale control plane. These tests are skipped unless the TF_ACC environment variable is set. Running make testacc sets the TF_ACC variable and runs the tests.

The TF_ACC environment variable is handled by Terraform core code and is not directly referenced in provider code.

The following tailscale specific environment variables must also be set:

• TAILSCALE_BASE_URL
  • URL of the control plane
• TAILSCALE_API_KEY
  • Tests will be performed against the tailnet which the key belongs to
• TAILSCALE_TEST_DEVICE_NAME
  • The FQDN of a device owned by the owner of the API key in use

Releasing

Pushing a tag of the format vX.Y.Z will trigger the release workflow which uses goreleaser to build and sign artifacts and generate a GitHub release.

GitHub releases are pulled in and served by the HashiCorp Terrafrom and OpenTofu registries for usage of the provider via Terraform or OpenTofu.