# Run the Teleport Terraform Provider Locally This guide covers how to run the Teleport Terraform provider from your local computer, where you are already logged in Teleport as yourself. This guide does not cover running Teleport in remote environments such as a cloud VM, an on-prem server, or CI/CD pipelines. If you are in one of those cases, please follow the dedicated guides: - [Run the Terraform Provider in CI or cloud VMs](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider/ci-or-cloud.md) - [Run the Terraform Provider on a server](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider/dedicated-server.md) ## How it works This setup relies on the user's local credentials (from `tsh login`) to create a temporary bot in Teleport, connect as the bot to obtain short-lived credentials, and export those credentials in the shell's environment variables. Every Terraform command run in this same terminal will then read credentials from environment variables and be able to connect to Teleport as the temporary bot. ## Prerequisites - A running Teleport cluster - Local tsh/tctl clients - Being locally logged in Teleport with a role that allows creating Bot and Token resources. You can use the default `editor` role for this. To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.7.3 CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` Validate that you meet the version requirements (16.2 or greater) by running: ``` $ tsh status Teleport v18.7.3 go1.25.9 Proxy version: 18.7.3 Proxy: teleport.example.com:443 ``` ## Step 1/2. Generate temporary bot credentials In this step, you will use `tctl` and your local credentials to create a temporary bot in Teleport for the Terraform provider. The bot will exist for one hour and will be granted the default `terraform-provider` role that can edit every resource the TF provider supports. `tctl` will then obtain credentials for the temporary bot and export them in your shell's environment variables. If [MFA for Administrative Actions](https://goteleport.com/docs/zero-trust-access/authentication/mfa-for-admin-actions.md) is enabled on your cluster, `tctl` will prompt for your MFA. Run the following command, do not remove the `eval` as it is required to load credentials in your shell: ``` $ eval "$(tctl terraform env)" 🔑 Detecting if MFA is required This is an admin-level action and requires MFA to complete Tap any security key Detected security key tap ⚙️ Creating temporary bot "tctl-terraform-env-82ab1a2e" and its token 🤖 Using the temporary bot to obtain certificates 🚀 Certificates obtained, you can now use Terraform in this terminal for 1h0m0s ``` ## Step 2/2. Run the Terraform provider At this point, you got valid credentials in your shell's environment variables for one hour. You can run the Teleport Terraform provider from this shell. --- IMPORTANT Only the shell you ran `eval "$(tctl terraform env)"` in has the Bot credentials. If you close this shell or open a new one, you will need to do the first step again. --- 1. Create a `main.tf` file containing this minimal Terraform code: ``` terraform { required_providers { teleport = { source = "terraform.releases.teleport.dev/gravitational/teleport" version = "~> 18.0" } } } provider "teleport" { addr = "teleport.example.com:443" } # We must create a test role, if we don't declare resources, Terraform won't try to # connect to Teleport and we won't be able to validate the setup. resource "teleport_role" "test" { version = "v7" metadata = { name = "test" description = "Dummy role to validate Terraform Provider setup" labels = { test = "yes" } } spec = {} } ``` 2. Then, init your Terraform working directory to download the Teleport provider: ``` $ terraform init Initializing the backend... Initializing provider plugins... - Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ... ``` 3. Finally, run a Terraform plan: ``` $ terraform plan Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + create Terraform will perform the following actions: # teleport_role.test will be created + resource "teleport_role" "test" { + id = (known after apply) + kind = (known after apply) + metadata = { + name = "test" + namespace = (known after apply) } + spec = {} + version = "v7" } Plan: 1 to add, 0 to change, 0 to destroy. ``` If the plan succeeds, the Terraform provider successfully connected to Teleport. You can now start developing locally with the Teleport Terraform provider. Do not forget to obtain new temporary credentials every hour by re-running `eval $(tctl terraform env)`. ## Next steps - Follow [the user and role IaC guide](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/managing-resources/user-and-role.md) to use the Terraform Provider to create Teleport users and grant them roles. - Consult the list of Terraform-supported resources [in the Terraform reference](https://goteleport.com/docs/reference/infrastructure-as-code/terraform-provider.md). - Once you have working Terraform code that configures your Teleport cluster, you might want to run it in the CI or from a bastion instead of running it locally. To do this, please follow the dedicated guides: - [Run the Terraform Provider in CI or cloud VMs](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider/ci-or-cloud.md) - [Run the Terraform Provider on a dedicated server](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider/dedicated-server.md)