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 andtsh
client tool version >= 9.3.7.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport 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 andtsh
client tool version >= 9.3.7, which you can download by visiting the customer portal.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport 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 andtsh
client tool version >= 9.3.8. To download these tools, visit the Downloads page.tctl versionTeleport v9.3.8 go1.17
tsh versionTeleport v9.3.8 go1.17
-
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 statusCluster 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 statusCluster 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-terraformcd 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:
lsmain.tf terraform-identity terraform-impersonator.yaml terraform.yaml
lsmain.tf auth.crt auth.key auth.cas terraform-impersonator.yaml terraform.yaml
Init terraform and apply the spec:
terraform initterraform apply
Next Steps
- Find the full list of supported Terraform provider resources.
- Read more about impersonation.