
Teleport
Terraform Provider
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise

Teleport Terraform Provider
Length: 07:38
This guide demonstrates how to:
- Set up the Terraform provider for Teleport on Linux and macOS.
- Configure Teleport users and roles using the Terraform provider.
Prerequisites
-
A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.0.1.See Installation for details.
-
A Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 13.3.9.You can download these tools from the Cloud Downloads page.
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.1.You can download these tools by visiting your Teleport account workspace.
Please use the latest version of Teleport Enterprise documentation.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com
-
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 runtctl
commands on your administrative workstation using your current credentials. For example:tsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.1
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 subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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. You can create a local Teleport user for this purpose or you can use the machine identity agent (Machine ID) to generate credentials.
If you intend to run Terraform from a CI/CD platform, Machine ID is often a better option for generating credentials. Machine ID can provision ephemeral short-lived certificates that are appropriate for CI/CD workflows instead of using manually-generated credentials that have a longer time-to-live (TTL) period. For more information about using Machine ID, see the Machine ID Getting Started Guide.
To prepare credentials for a local Teleport user:
-
Create a folder called
teleport-terraform
to hold temporary files:mkdir -p teleport-terraformcd teleport-terraform -
Create a new file called
terraform.yaml
and open it in an editor. -
Configure settings for a local Teleport user and role by pasting the following content into the
terraform.yaml
file:kind: role metadata: name: terraform spec: allow: db_labels: '*': '*' app_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 verbs: ['list','create','read','update','delete'] version: v7 --- kind: user metadata: name: terraform spec: roles: ['terraform'] version: v2
These settings configure a user and role named
terraform
with the permissions required to manage resources in your Teleport cluster. -
Create the
terraform
user and role by running the following command:tctl create terraform.yamlThe
terraform
user can't sign in to get credentials, so you must have another user impersonate theterraform
account to request a certificate. -
Create a new file called
terraform-impersonator.yaml
and open it in an editor. -
Configure a role that enables your user to impersonate the Terraform user by pasting the following content into the
terraform-impersonator.yaml
file:kind: role version: v7 metadata: name: terraform-impersonator spec: allow: # This impersonate role allows any user assigned to this role to impersonate # and generate certificates for the user named "terraform" with a role also # named "terraform". impersonate: users: ['terraform'] roles: ['terraform']
-
Create the
terraform-impersonator
role by running the following command:tctl create terraform-impersonator.yaml -
Assign the
terraform-impersonator
role to your Teleport user by running the appropriate commands for your authentication provider:-
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml -
Edit
out.yaml
, addingterraform-impersonator
to the list of existing roles:roles: - access - auditor - editor + - terraform-impersonator
-
Apply your changes:
tctl create -f out.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
github
authentication connector:tctl get github/github --with-secrets > github.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thegithub.yaml
file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource. -
Edit
github.yaml
, addingterraform-impersonator
to theteams_to_roles
section.The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.
Here is an example:
teams_to_roles: - organization: octocats team: admins roles: - access + - terraform-impersonator
-
Apply your changes:
tctl create -f github.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
saml
configuration resource:tctl get --with-secrets saml/mysaml > saml.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thesaml.yaml
file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. -
Edit
saml.yaml
, addingterraform-impersonator
to theattributes_to_roles
section.The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
attributes_to_roles: - name: "groups" value: "my-group" roles: - access + - terraform-impersonator
-
Apply your changes:
tctl create -f saml.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
oidc
configuration resource:tctl get oidc/myoidc --with-secrets > oidc.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to theoidc.yaml
file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. -
Edit
oidc.yaml
, addingterraform-impersonator
to theclaims_to_roles
section.The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
claims_to_roles: - name: "groups" value: "my-group" roles: - access + - terraform-impersonator
-
Apply your changes:
tctl create -f oidc.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
-
Request a signed identity file for the Terraform user by running the following command:
tctl auth sign --user=terraform --out=terraform-identityAfter running this command, you have a
terraform-identity
file with credentials for the Terraform user.
Step 2/3. Prepare a Terraform configuration file
To prepare a Terraform configuration file:
-
Create a new file called
main.tf
and open it in an editor. -
Define an example user and role using Terraform by pasting the following content into the
main.tf
file:terraform { required_providers { teleport = { source = "terraform.releases.teleport.dev/gravitational/teleport" version = ">= 14.0.1" } } } 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" } resource "teleport_role" "terraform-test" { metadata = { name = "terraform-test" description = "Terraform test role" labels = { example = "yes" } } spec = { options = { forward_agent = false max_session_ttl = "30m" port_forwarding = false client_idle_timeout = "1h" disconnect_expired_cert = true permit_x11_forwarding = false request_access = "denied" } allow = { logins = ["this-user-does-not-exist"] rules = [ { resources = ["user", "role"] verbs = ["list"] } ] request = { roles = ["example"] claims_to_roles = [ { claim = "example" value = "example" roles = ["example"] } ] } node_labels = { key = ["example"] alabel = ["with", "multiple", "values"] } } deny = { logins = ["anonymous"] } } } resource "teleport_user" "terraform-test" { metadata = { name = "terraform-test" description = "Test terraform user" expires = "2022-10-12T07:20:50Z" labels = { test = "true" } } spec = { roles = ["terraform-test"] } }
terraform { required_providers { teleport = { source = "terraform.releases.teleport.dev/gravitational/teleport" version = ">= 14.0.1" } } } 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" } resource "teleport_role" "terraform-test" { metadata = { name = "terraform-test" description = "Terraform test role" labels = { example = "yes" } } spec = { options = { forward_agent = false max_session_ttl = "30m" port_forwarding = false client_idle_timeout = "1h" disconnect_expired_cert = true permit_x11_forwarding = false request_access = "denied" } allow = { logins = ["this-user-does-not-exist"] rules = [ { resources = ["user", "role"] verbs = ["list"] } ] request = { roles = ["example"] claims_to_roles = [ { claim = "example" value = "example" roles = ["example"] } ] } node_labels = { key = ["example"] alabel = ["with", "multiple", "values"] } } deny = { logins = ["anonymous"] } } } resource "teleport_user" "terraform-test" { metadata = { name = "terraform-test" description = "Test terraform user" expires = "2022-10-12T07:20:50Z" labels = { test = "true" } } spec = { roles = ["terraform-test"] } }
Step 3/3. Apply the configuration
To apply the configuration:
-
Check the contents of the
teleport-terraform
folder:lsmain.tf terraform-identity terraform-impersonator.yaml terraform.yaml
-
Initialize the working directory that contains Terraform configuration files by running the following command:
terraform init -
Execute the Terraform plan defined in the configuration file by running the following command:
terraform apply
Next steps
- Explore the full list of supported Terraform provider resources.
- Read more about impersonation.