Teleport

Terraform Provider

Improve

Teleport Terraform Provider

Length: 07:38

This guide will explain how to:

Set up Teleport's Terraform provider on Linux and Mac.
Configure Teleport users and roles using the Terraform provider.

Prerequisites

A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 9.3.7.
```
tctl version
Teleport v9.3.7 go1.17
tsh version
Teleport v9.3.7 go1.17
```
See Installation for details.

A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The tctl admin tool and tsh client tool version >= 9.3.7, which you can download by visiting the customer portal.
```
tctl version
Teleport v9.3.7 go1.17
tsh version
Teleport v9.3.7 go1.17
```

A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.
The tctl admin tool and tsh client tool version >= 9.3.8. To download these tools, visit the Downloads page.
```
tctl version
Teleport v9.3.8 go1.17
tsh version
Teleport v9.3.8 go1.17
```

Terraform >= 1.0.0+
```
terraform version
Terraform v1.0.0
```

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  9.3.7
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  9.3.8
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

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

mkdir -p teleport-terraform
cd teleport-terraform

Step 1/3. Create a Terraform user

Enable impersonation

In order for Terraform to manage resources in your Teleport cluster, it needs a signed identity file from the cluster's certificate authority. The Terraform user cannot request this itself, and requires another user to impersonate this account in order to request a certificate.

Create a role that enables your user to impersonate the Terraform user. First, paste the following YAML document into a file called terraform-impersonator.yaml:

kind: role
version: v5
metadata:
  name: terraform-impersonator
spec:
  # SSH options used for user sessions
  options:
    # max_session_ttl defines the TTL (time to live) of SSH certificates
    # issued to the users with this role.
    max_session_ttl: 10h

  # The allow section declares a list of resource/verb combinations that are
  # allowed for the users of this role. By default, nothing is allowed.
  allow:
    impersonate:
      users: ['terraform']
      roles: ['terraform']

  # The deny section uses the identical format as the 'allow' section.
  # Deny rules always override allow rules.
  deny:
    node_labels:
      '*': '*'

Next, create the role:

tctl create terraform-impersonator.yaml

Assign this role to the current user. Log in to your Teleport cluster to assume the new role.

Create the Terraform user

Put the following content into terraform.yaml:

kind: role
metadata:
  name: terraform
spec:
  allow:
    rules:
      - resources: ['user', 'role', 'token', 'trusted_cluster', 'github', 'oidc', 'saml']
        verbs: ['list','create','read','update','delete']
version: v5
---
kind: user
metadata:
  name: terraform
spec:
  roles: ['terraform']
version: v2

Create the terraform user and role.

tctl create terraform.yaml

Next, request a signed certificate for the Terraform user:

tctl auth sign --format=tls --user=terraform --out=auth

This command should result in three PEM-encoded files: auth.crt, auth.key, and auth.cas (certificate, private key, and CA certs, respectively).

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

The above sequence should result in one PEM-encoded file: terraform-identity.

Step 2/3. Create a Terraform configuration

Paste the following into a file called main.tf to define an example user and role using Terraform.

terraform {
  required_providers {
    teleport = {
      source  = "terraform.releases.teleport.dev/gravitational/teleport"
      version = ">= 9.3.7"
    }
  }
}

provider "teleport" {
  # Update addr to point to your Teleport Cloud tenant URL
  addr               = "mytenant.teleport.sh"
  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"
         value = ["yes"]
      }
    }

    deny {
      logins = ["anonymous"]
    }
  }
}

resource "teleport_user" "terraform-test" {
  metadata {
    name        = "terraform-test"
    description = "Test terraform user"
    expires     = "2022-10-12T07:20:50.52Z"

    labels = {
      test      = "true"
    }
  }

  spec {
    roles = ["terraform-test"]
  }
}

terraform {
  required_providers {
    teleport = {
      source  = "terraform.releases.teleport.dev/gravitational/teleport"
      version = ">= 9.3.7"
    }
  }
}

provider "teleport" {
  # Update addr to point to Teleport Auth/Proxy
  # addr               = "auth.example.com:3025"
  addr               = "proxy.example.com:443"
  cert_path          = "auth.crt"
  key_path           = "auth.key"
  root_ca_path       = "auth.cas"
}

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"
         value = ["yes"]
      }
    }

    deny {
      logins = ["anonymous"]
    }
  }
}

resource "teleport_user" "terraform-test" {
  metadata {
    name        = "terraform-test"
    description = "Test terraform user"
    expires     = "2022-10-12T07:20:50.52Z"

    labels = {
      test      = "true"
    }
  }

  spec {
    roles = ["terraform-test"]
  }
}

Step 3/3. Apply the configuration

Check the contents of the teleport-terraform folder:

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

ls
main.tf  auth.crt  auth.key  auth.cas  terraform-impersonator.yaml  terraform.yaml

Init terraform and apply the spec:

terraform init
terraform apply

Next Steps

Find the full list of supported Terraform provider resources.
Read more about impersonation.

Have a suggestion or can’t find something?

IMPROVE THE DOCS