Terraform Provider

This guide demonstrates how to: Set up the Terraform provider for Teleport on Linux and macOS.

Terraform is intended to be used with Machine ID, Teleport's feature for providing identities to machines and services, rather than users. This tutorial will show you how to use a local Machine ID bot to try it out.

For instructions on managing users and roles via Terraform, read the "Managing users and roles with IaC" guide.

For instructions on managing the Teleport dynamic resources as code using GitOps, read the guide to using the Teleport Terraform provider with Spacelift and Machine ID.

Prerequisites

• A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool version >= 15.2.2.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• Terraform >= 1.0.0+

  terraform version
  Terraform v1.0.0

• 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 --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.2
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/3. Create Teleport credentials for Terraform

Terraform needs a signed identity file from the Teleport cluster certificate authority to manage resources in the cluster. To prepare credentials using a local Teleport bot:

1. Create a folder called teleport-terraform to hold temporary files:

   mkdir -p teleport-terraform
   cd teleport-terraform

2. Create a new file called terraform.yaml and open it in an editor.

3. Terraform needs a role giving it permission to manage our Cluster's resources. The bot will create identity certificates that have this role. Configure the necessary role by pasting the following content into a terraform_role.yaml file:

   kind: role
   metadata:
     name: terraform
   spec:
     allow:
       db_labels:
         '*': '*'
       app_labels:
         '*': '*'
       node_labels:
         '*': '*'
       rules:
         - resources:
           - app
           - cluster_auth_preference
           - cluster_networking_config
           - db
           - device
           - github
           - login_rule
           - oidc
           - okta_import_rule
           - role
           - saml
           - session_recording_config
           - token
           - trusted_cluster
           - user
           - access_list
           - node
           verbs: ['list','create','read','update','delete']
   version: v7
   

   These settings configure a role named terraform with the permissions required to manage resources in your Teleport cluster.

4. Create the terraform role by running the following command:

   tctl create -f terraform_role.yaml
   role 'terraform' has been created

5. We're going to create two scripts that will let us quickly and repeatably create and destroy our local Terraform bot. First, create a new file called create_and_run_terraform_bot.sh, open it in an editor, and paste in the following content:

   #! /usr/bin/env bash
   
   TOKEN=$(tctl bots add terraform-test --roles=terraform --format=json | jq -r '.token_id')
   tbot start \
     --destination-dir=./terraform-identity \
     --token="$TOKEN" \
     --data-dir=./tbot-data \
     --join-method=token \
     --auth-server=tele.example.com:443
     # Replace with the host and port of your Teleport Auth Service
     # or Teleport Proxy Service
   

   When run, this creates a new bot with the token retrieved from the JSON output. That token is piped into the start command. For security reasons, we don't allow bot join tokens to be created in any way other than adding a bot, so for local development work, you must manually manage the bot and its token.

6. Create another file called remove_terraform_bot.sh, open it in an editor, and paste in the following content:

   #! /usr/bin/env bash
   
   tctl bots rm terraform-test
   rm -rf ./terraform-identity
   

   This script will be used later to clean up our bot in between runs and when we're done.

7. In a new terminal window, run the create_and_run_terraform_bot.sh script to create the new bot and start it:

   chmod +x create_and_run_terraform_bot.sh
   ./create_and_run_terraform_bot.sh

Step 2/3. Prepare a Terraform configuration file

To prepare a Terraform configuration file:

1. Create a new file called provider.tf and open it in an editor.

2. Use the Teleport Terraform provider and connect it to your Teleport cluster by pasting the following content into the provider.tf file:

   • Cloud-Hosted
   • Self-Hosted

   terraform {
     required_providers {
       teleport = {
         source  = "terraform.releases.teleport.dev/gravitational/teleport"
         version = "~> 15.0"
       }
     }
   }
   
   provider "teleport" {
     # Update addr to point to your Teleport Cloud tenant URL's host:port
     addr               = "mytenant.teleport.sh:443"
     identity_file_path = "terraform-identity/identity"
   }
   
   # creates 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 = {
     }
   }
   
   

   terraform {
     required_providers {
       teleport = {
         source  = "terraform.releases.teleport.dev/gravitational/teleport"
         version = "~> 15.0"
       }
     }
   }
   
   provider "teleport" {
     # Update addr to point to Teleport Auth/Proxy
     # addr              = "auth.example.com:3025"
     addr               = "proxy.example.com:443"
     identity_file_path = "terraform-identity/identity"
   }
   
   # creates 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 = {
     }
   }
   
   

Step 3/3. Validate the configuration

To apply the configuration:

1. Check the contents of the teleport-terraform folder:

   ls
   provider.tf  terraform-identity/  create_and_run_terraform_bot.sh remove_terraform_bot.sh  terraform_role.yaml

2. Initialize the working directory that contains Terraform configuration files by running the following command:

   terraform init

3. Execute the Terraform plan defined in the configuration file by running the following command:

   terraform apply

4. When you're done, use Ctrl-C to stop the Terraform bot. Then run the remove_terraform_bot.sh script to remove the bot and clean up the terraform-identity folder:

   chmod +x remove_terraform_bot.sh
   ./remove_terraform_bot.sh

   If you need to start the bot back up, you can run the two bot scripts as many times as necessary.

Next steps

• Follow the user and role IaC guide to use the Terraform Provider to create Teleport users and grant them roles.
• Explore the full list of supported Terraform provider resources.
• See how to use Machine ID with Terraform in production.