Fork me on GitHub

Teleport

Terraform Provider

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise
Teleport Terraform Provider

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 and tsh client tool version >= 14.2.1.

    See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport v14.2.1 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.2.1 go1.21

Proxy version: 14.2.1Proxy: teleport.example.com
  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 14.1.3.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.1.3 go1.21

Proxy version: 14.1.3Proxy: teleport.example.com
  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

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

    You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.2.1 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.2.1 go1.21

Proxy version: 14.2.1Proxy: teleport.example.com
  • A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.

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

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.1.3 go1.21

Proxy version: 14.1.3Proxy: teleport.example.com
  • 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 14.2.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 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 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:

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

  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:

    1. Retrieve your local user's configuration resource:

      tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
    2. Edit out.yaml, adding terraform-impersonator to the list of existing roles:

        roles:
         - access
         - auditor
         - editor
      +  - terraform-impersonator 
      
    3. Apply your changes:

      tctl create -f out.yaml
    4. Sign out of the Teleport cluster and sign in again to assume the new role.

    1. Retrieve your github authentication connector:

      tctl get github/github --with-secrets > github.yaml

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

    2. Edit github.yaml, 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:

      tctl create -f github.yaml
    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 = "~> 14.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"
    }
    
    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"
        }
      }
    }
    
    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:

  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
  3. Execute the Terraform plan defined in the configuration file by running the following command:

    terraform apply

Next steps