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

Teleport Terraform Provider

The Teleport Terraform provider allows Terraform users to configure Teleport from Terraform.

This section is the Teleport Terraform Provider reference. It lists all the supported resources and their fields.

tip

To get started with the Terraform provider, you must start with the installation guide. Once you got a working provider, we recommend you to follow the "Managing users and roles with IaC" guide.

The provider exposes Teleport resources both as Terraform data-sources and Terraform resources. Data-sources are used by Terraform to fetch information from Teleport, while resources are used to create resources in Teleport.

Example Usage​

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"
}

Connection methods​

This section lists the different ways of passing credentials to the Terraform provider. You can find which method fits your use case in the Teleport Terraform provider setup page

With an identity file​

With this connection method, you must provide an identity file.This file allows Terraform to connect both via the Proxy Service (ports 443 or 3080) and via the Auth Service (port 3025). This is the recommended way of passing credentials to the Terraform provider.

The identity file can be obtained via several ways:

Obtaining an identity file locally with tctl​

Since 16.2, you can use tctl and your local credentials to create a temporary bot and load its identity in your shell's environment variables:

$ 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

You can find more information in the "Run the Terraform provider locally" guide

Obtaining an identity file via tbot​

tbot relies on MachineID to obtain and automatically renew short-lived credentials. Such credentials are harder to exfiltrate, and you can control more precisely who has access to which roles (e.g. you can allow only GitHub Actions pipelines targeting the prod environment to get certificates).

You can follow the Terraform Provider guide to setup tbot and have Terraform use its identity.

Obtaining an identity file via tctl auth sign​

You can obtain an identity file with the command

$ tctl auth sign --user terraform --format file -o identity.pem

This auth method has the following limitations:

  • Such credentials are high-privileged and long-lived. They must be protected and rotated.
  • This auth method does not work against Teleport clusters with MFA set to webauthn. On such clusters, Teleport will reject any long-lived certificate and require an additional MFA challenge for administrative actions.

With a token (native MachineID)​

Starting with 16.2, the Teleport Terraform provider can natively use MachineID (without tbot) to join a Teleport cluster. The Terraform Provider will rely on its runtime (AWS, GCP, Kubernetes, CI/CD system) to prove its identity to Teleport.

You can use any delegated join method by setting both join_method and join_token in the provider configuration.

This setup is described in more details in the "Run the Teleport Terraform provider in CI or Cloud" guide.

With key, certificate, and CA certificate​

With this connection method, you must provide a TLS key, a TLS certificate, and the Teleport Auth Service TLS CA certificates. Those can be obtained with the command:

$ tctl auth sign --user terraform --format=tls -o terraform.pem

This auth method has the following limitations:

  • The provider can only connect to the Auth directly (port 3025). On most clusters, only the proxy is publicly exposed.
  • Such credentials are high-privileged and long-lived. They must be protected and rotated.
  • This auth method does not work against Teleport clusters with MFA set to webauthn. On such clusters, Teleport will reject any long-lived certificate and require an additional MFA challenge for administrative actions.

Schema​

Optional​

  • addr (String) host:port of the Teleport address. This can be the Teleport Proxy Service address (port 443 or 4080) or the Teleport Auth Service address (port 3025). This can also be set with the environment variable TF_TELEPORT_ADDR.
  • audience_tag (String) Name of the optional audience tag used for native Machine ID joining with the terraform method. This can also be set with the environment variable TF_TELEPORT_JOIN_AUDIENCE_TAG.
  • cert_base64 (String) Base64 encoded TLS auth certificate. This can also be set with the environment variable TF_TELEPORT_CERT_BASE64.
  • cert_path (String) Path to Teleport auth certificate file. This can also be set with the environment variable TF_TELEPORT_CERT.
  • dial_timeout_duration (String) DialTimeout sets timeout when trying to connect to the server. This can also be set with the environment variable TF_TELEPORT_DIAL_TIMEOUT_DURATION.
  • identity_file (String, Sensitive) Teleport identity file content. This can also be set with the environment variable TF_TELEPORT_IDENTITY_FILE.
  • identity_file_base64 (String, Sensitive) Teleport identity file content base64 encoded. This can also be set with the environment variable TF_TELEPORT_IDENTITY_FILE_BASE64.
  • identity_file_path (String) Teleport identity file path. This can also be set with the environment variable TF_TELEPORT_IDENTITY_FILE_PATH.
  • join_method (String) Enables the native Terraform MachineID support. When set, Terraform uses MachineID to securely join the Teleport cluster and obtain credentials. See the join method reference for possible values. You must use a delegated join method. This can also be set with the environment variable TF_TELEPORT_JOIN_METHOD.
  • join_token (String) Name of the token used for the native MachineID joining. This value is not sensitive for delegated join methods. This can also be set with the environment variable TF_TELEPORT_JOIN_TOKEN.
  • key_base64 (String, Sensitive) Base64 encoded TLS auth key. This can also be set with the environment variable TF_TELEPORT_KEY_BASE64.
  • key_path (String) Path to Teleport auth key file. This can also be set with the environment variable TF_TELEPORT_KEY.
  • profile_dir (String) Teleport profile path. This can also be set with the environment variable TF_TELEPORT_PROFILE_PATH.
  • profile_name (String) Teleport profile name. This can also be set with the environment variable TF_TELEPORT_PROFILE_NAME.
  • retry_base_duration (String) Retry algorithm when the API returns 'not found': base duration between retries (https://pkg.go.dev/time#ParseDuration). This can also be set with the environment variable TF_TELEPORT_RETRY_BASE_DURATION.
  • retry_cap_duration (String) Retry algorithm when the API returns 'not found': max duration between retries (https://pkg.go.dev/time#ParseDuration). This can also be set with the environment variable TF_TELEPORT_RETRY_CAP_DURATION.
  • retry_max_tries (String) Retry algorithm when the API returns 'not found': max tries. This can also be set with the environment variable TF_TELEPORT_RETRY_MAX_TRIES.
  • root_ca_base64 (String) Base64 encoded Root CA. This can also be set with the environment variable TF_TELEPORT_CA_BASE64.
  • root_ca_path (String) Path to Teleport Root CA. This can also be set with the environment variable TF_TELEPORT_ROOT_CA.