Run the Teleport Terraform Provider with Long-Lived Credentials

This guide explains you how to create a Terraform user and have the Teleport Auth Service sign long-lived credentials for it. The Teleport Terraform Provider can then user those credentials to interact with Teleport.

Prerequisites

• A running Teleport cluster version 16.4.7 or above. 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.

  Visit Installation for instructions on downloading tctl and tsh.

• 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.

  For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  16.4.7
  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. You will create a local Teleport user for this purpose.

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. Configure settings for a local Teleport user and role by pasting the following content into the terraform.yaml file:

   kind: user
   metadata:
     name: terraform
   spec:
     roles: ['terraform-provider']
   version: v2
   

   Starting with 16.2, Teleport comes with a built-in role for the Terraform provider: terraform-provider.

   RBAC for versions before v16.2

   On older version you will need to create the Terraform role yourself. Write the following role.yaml manifest:

   kind: role
   version: v7
   metadata:
     name: terraform-provider
   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']
   

   Use tctl create -f ./role.yaml to create the role.

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

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

   tctl create terraform.yaml

   The terraform user can't sign in to get credentials, so you must have another user impersonate the terraform account to request a certificate.

5. Create a new file called terraform-impersonator.yaml and open it in an editor.

6. 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']
   

7. Create the terraform-impersonator role by running the following command:

   tctl create terraform-impersonator.yaml

8. Assign the terraform-impersonator role to your Teleport user by running the appropriate commands for your authentication provider:

   • Local User
   • GitHub
   • SAML
   • OIDC

   1. Retrieve your local user's roles as a comma-separated list:

      ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')

   2. Edit your local user to add the new role:

      tctl users update $(tsh status -f json | jq -r '.active.username') \  --set-roles "${ROLES?},terraform-impersonator"

   3. Sign out of the Teleport cluster and sign in again to assume the new role.

   1. Open your github authentication connector in a text editor:

      tctl edit github/github

   2. Edit the github connector, adding terraform-impersonator to the teams_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
      

   3. Apply your changes by saving closing the file in your editor.

   4. Sign out of the Teleport cluster and sign in again to assume the new role.

   1. Retrieve your saml configuration resource:

      tctl get --with-secrets saml/mysaml > saml.yaml

      Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the saml.yaml file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.

   2. Edit saml.yaml, adding terraform-impersonator to the attributes_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
      

   3. Apply your changes:

      tctl create -f saml.yaml

   4. Sign out of the Teleport cluster and sign in again to assume the new role.

   1. Retrieve your oidc configuration resource:

      tctl get oidc/myoidc --with-secrets > oidc.yaml

      Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the oidc.yaml file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.

   2. Edit oidc.yaml, adding terraform-impersonator to the claims_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
      

   3. Apply your changes:

      tctl create -f oidc.yaml

   4. Sign out of the Teleport cluster and sign in again to assume the new role.

9. Request a signed identity file for the Terraform user by running the following command:

   tctl auth sign --user=terraform --out=terraform-identity

   After 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:

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

2. 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 = "~> 16.0"
         }
      }
   }
   
   provider "teleport" {
      addr               = 'teleport.example.com:443'
      identity_file_path = "terraform-identity"
   }
   
   # 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 = {}
   }
   

Step 3/3. Apply the configuration

To apply the configuration:

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

   ls
   main.tf  terraform-identity  terraform-impersonator.yaml  terraform.yaml

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

   terraform init
   Initializing the backend...
   Initializing provider plugins...- Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ...

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

   terraform apply
   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.

Next steps

• Explore the full list of supported Terraform provider resources.
• Learn how to manage users and roles with IaC
• Read more about impersonation.