Teleport

Terraform Provider

Improve

Teleport Terraform Provider

Length: 07:38

This section will cover:

Setting up Teleport's terraform provider on Linux and Mac.
Configuring users and roles using terraform provider for Cloud, Enterprise and Open Source editions.

Prerequisites

Terraform >= 0.12.0+
Teleport 7.1.3 Cloud, Open Source or Enterprise

terraform version

Terraform v0.12.0

tctl version
Teleport v7.1.3 go(teleport.golang)

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

mkdir -p teleport-terraform
cd teleport-terraform

Step 1/4. Install terraform provider

mkdir -p ${HOME?}/.terraform.d/plugins/gravitational.com/teleport/teleport/7.1.3/linux_amd64
curl -L -O https://get.gravitational.com/terraform-provider-teleport-v7.1.3-linux-amd64-bin.tar.gz
tar -zxvf terraform-provider-teleport-v7.1.3-linux-amd64-bin.tar.gz -C ${HOME?}/.terraform.d/plugins/gravitational.com/teleport/teleport/7.1.3/linux_amd64

Step 2/4. Create a 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: v4
---
kind: user
metadata:
  name: terraform
spec:
  roles: ['terraform']
version: v2

Run:

tctl create terraform.yaml
tctl auth sign --format=file --user=terraform --out=terraform-identity --ttl=10h

Note

Clients missing impersonation privileges when trying to use tctl auth sign, will get the following error:

ERROR: access denied: impersonation is not allowed

Create the following file with role: terraform-impersonator.yaml:

kind: role
version: v4
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

  # 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.
  # the deny rules always override allow rules.
  deny:
    node_labels:
      '*': '*'

tctl create terraform-impersonator.yaml

Assign this role to the current user. Re-login to assume the new role and try to issue certificate for terraform user again.

Step 3/4. Create Terraform configuration

Create a main.tf terraform file:

terraform {
  required_providers {
    teleport = {
      version = ">= 7.1.3"
      source  = "gravitational.com/teleport/teleport"
    }
  }
}

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_x11forwarding    = 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"]
  }
}

Note

Update teleport.example.com:443 with the address of your Teleport cluster.

Step 4/4. Apply the configuration

Check the contents of teleport-terraform folder:

main.tf terraform-identity 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