Skip to main content
Version: 17.x (unreleased)

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:

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 whose version is higher than 16.2
  • Local tsh/tctl clients with versions higher than 16.2
  • 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. tctl is supported on macOS and Linux machines.

For example:

$ tsh login --proxy=teleport.example.com:443 --user=email@example.com
$ tctl status
# Cluster  teleport.example.com
# Version  17.0.0-dev
# CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

Validate that you meet the version requirements (16.2 or greater) by running:

$ tsh status
Teleport v17.0.0-dev go1.22
Proxy version: 17.0.0-dev
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 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 = "~> 17.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​