Terraform provider resources

Supported resources:

• teleport_access_list
• teleport_app
• teleport_auth_preference
• teleport_bot
• teleport_cluster_maintenance_config
• teleport_cluster_networking_config
• teleport_database
• teleport_github_connector
• teleport_login_rule
• teleport_oidc_connector
• teleport_okta_import_rule
• teleport_provision_token
• teleport_role
• teleport_saml_connector
• teleport_session_recording_config
• teleport_trusted_cluster
• teleport_trusted_device
• teleport_user

Provider configuration

Ensure your Terraform version is v1.0.0 or higher.

Add the following configuration section to your terraform configuration block:

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

The provider supports the following options:

You need to specify at least one of:

• cert_path, key_path,root_ca_path and addr to connect using key files.
• cert_base64, key_base64,root_ca_base64 and addr to connect using a base64-encoded key.
• identity_file_path or identity_file_base64 and addr to connect using an identity file.
• profile_name, profile_dir (both can be empty) and addr to connect using current profile from ~/.tsh

The retry_* values are used to retry the API calls to Teleport when the cache is stale.

If more than one are provided, they will be tried in the order above until one succeeds.

Example:

provider "teleport" {
  addr         = "localhost:3025"
  cert_path    = "tf.crt"
  key_path     = "tf.key"
  root_ca_path = "tf.ca"
}

Provider resource versioning

Since Teleport 15, you must set the version on each resource, and version cannot be changed in-place. Terraform will delete the resource and create a new one if a version change is required.

This is not enforced on previous Teleport provider versions, but we recommend doing so. When the version is not specified, Terraform will pick the latest one by default. However, version upgrades don't re-apply the resource defaults. This could lead to different results if you create a new resource or upgrade an existing one. To mitigate this, you should explicitly set the resource version.

resource "teleport_role" "test" {
  version = "v5"
  metadata = {
    name = "my-role"
  }
  // ...
}

teleport_access_list

header

header is the header for the resource.

header.metadata

metadata is resource metadata.

spec

spec is the specification for the access list.

spec.audit

audit describes the frequency that this access list must be audited.

spec.audit.notifications

notifications is the configuration for notifying users.

spec.audit.recurrence

recurrence is the recurrence definition

spec.grants

grants describes the access granted by membership to this access list.

spec.grants.traits

traits are the traits that are granted to users who are members of the access list.

spec.membership_requires

membership_requires describes the requirements for a user to be a member of the access list. For a membership to an access list to be effective, the user must meet the requirements of Membership_requires and must be in the members list.

spec.membership_requires.traits

traits are the traits that must be present for the user to obtain access.

spec.owner_grants

owner_grants describes the access granted by owners to this access list.

spec.owner_grants.traits

traits are the traits that are granted to users who are members of the access list.

spec.owners

owners is a list of owners of the access list.

spec.ownership_requires

ownership_requires describes the requirements for a user to be an owner of the access list. For ownership of an access list to be effective, the user must meet the requirements of ownership_requires and must be in the owners list.

spec.ownership_requires.traits

traits are the traits that must be present for the user to obtain access.

Example:

resource "teleport_access_list" "crane-operation" {
  header = {
    metadata = {
      name = "crane-operation"
      labels = {
        example = "yes"
      }
    }
  }
  spec = {
    description = "Used to grant access to the crane."
    owners = [
      {
        name = "gru"
        description = "The supervillain."
      }
    ]
    membership_requires = {
      roles = ["minion"]
    }
    ownership_requires = {
      roles = ["supervillain"]
    }
    grants = {
      roles = ["crane-operator"]
      traits = [{
        key = "allowed-machines"
        values = ["crane", "forklift"]
      }]
    }
    title = "Crane operation"
    audit = {
      recurrence = {
        frequency = 3 # audit every 3 months
        day_of_month = 15 # audit happen 15's day of the month. Possible values are 1, 15, and 31.
      }
    }
  }
}

teleport_app

metadata

Metadata is the app resource metadata.

spec

Spec is the app resource spec.

spec.aws

AWS contains additional options for AWS applications.

spec.dynamic_labels

DynamicLabels are the app's command labels.

spec.rewrite

Rewrite is a list of rewriting rules to apply to requests and responses.

spec.rewrite.headers

Headers is a list of headers to inject when passing the request over to the application.

Example:

# Teleport App

resource "teleport_app" "example" {
  metadata = {
    name = "example"
    description = "Test app"
    labels = {
        "teleport.dev/origin" = "dynamic" // This label is added on Teleport side by default
    }
  }

  spec = {
    uri = "localhost:3000"
  }
}

teleport_auth_preference

metadata

Metadata is resource metadata

spec

Spec is an AuthPreference specification

spec.device_trust

DeviceTrust holds settings related to trusted device verification. Requires Teleport Enterprise.

spec.hardware_key

HardwareKey are the settings for hardware key support.

spec.hardware_key.serial_number_validation

SerialNumberValidation holds settings for hardware key serial number validation. By default, serial number validation is disabled.

spec.idp

IDP is a set of options related to accessing IdPs within Teleport. Requires Teleport Enterprise.

spec.idp.saml

SAML are options related to the Teleport SAML IdP.

spec.okta

Okta is a set of options related to the Okta service in Teleport. Requires Teleport Enterprise.

spec.u2f

U2F are the settings for the U2F device.

spec.webauthn

Webauthn are the settings for server-side Web Authentication support.

Example:

# AuthPreference resource

resource "teleport_auth_preference" "example" {
  metadata = {
    description = "Auth preference"
    labels = {
      "example" = "yes"
      "teleport.dev/origin" = "dynamic" // This label is added on Teleport side by default
    }
  }

  spec = {
    disconnect_expired_cert = true
  }
}

teleport_bot

Example:

# Teleport Machine ID Bot creation example

locals {
  bot_name = "example"
}

resource "random_password" "bot_token" {
  length           = 32
  special          = false
}

resource "time_offset" "bot_example_token_expiry" {
  offset_hours = 1
}

resource "teleport_provision_token" "bot_example" {
  metadata = {
    expires = time_offset.bot_example_token_expiry.rfc3339
    description = "Bot join token for ${local.bot_name} generated by Terraform"

    name = random_password.bot_token.result
  }

  spec = {
    roles = ["Bot"]
    bot_name = local.bot_name
    join_method = "token"
  }
}

resource "teleport_bot" "example" {
  name = local.bot_name
  token_id = teleport_provision_token.bot_example.metadata.name
  roles = ["access"]
}

teleport_cluster_maintenance_config

metadata

Metadata is resource metadata

spec

spec.agent_upgrades

AgentUpgrades encodes the agent upgrade window.

Example:

# Teleport Cluster Networking config

resource "teleport_cluster_maintenance_config" "example" {
   metadata = {
    description = "Maintenance config"
  }

  spec = {
	agent_upgrades = {
	  utc_start_hour = 1
	  weekdays = [ "monday" ]
	}
  }
}

teleport_cluster_networking_config

metadata

Metadata is resource metadata

spec

Spec is a ClusterNetworkingConfig specification

spec.tunnel_strategy

TunnelStrategyV1 determines the tunnel strategy used in the cluster.

spec.tunnel_strategy.agent_mesh

spec.tunnel_strategy.proxy_peering

Example:

# Teleport Cluster Networking config

resource "teleport_cluster_networking_config" "example" {
   metadata = {
    description = "Networking config"
    labels = {
      "example" = "yes"
      "teleport.dev/origin" = "dynamic" // This label is added on Teleport side by default
    }
  }

  spec = {
    client_idle_timeout = "1h"
  }
}

teleport_database

metadata

Metadata is the database metadata.

spec

Spec is the database spec.

spec.ad

AD is the Active Directory configuration for the database.

spec.admin_user

AdminUser is the database admin user for automatic user provisioning.

spec.aws

AWS contains AWS specific settings for RDS/Aurora/Redshift databases.

spec.aws.elasticache

ElastiCache contains AWS ElastiCache Redis specific metadata.

spec.aws.memorydb

MemoryDB contains AWS MemoryDB specific metadata.

spec.aws.opensearch

OpenSearch contains AWS OpenSearch specific metadata.

spec.aws.rds

RDS contains RDS specific metadata.

spec.aws.rdsproxy

RDSProxy contains AWS Proxy specific metadata.

spec.aws.redshift

Redshift contains Redshift specific metadata.

spec.aws.redshift_serverless

RedshiftServerless contains AWS Redshift Serverless specific metadata.

spec.aws.secret_store

SecretStore contains secret store configurations.

spec.azure

Azure contains Azure specific database metadata.

spec.azure.redis

Redis contains Azure Cache for Redis specific database metadata.

spec.dynamic_labels

DynamicLabels is the database dynamic labels.

spec.gcp

GCP contains parameters specific to GCP Cloud SQL databases.

spec.mongo_atlas

MongoAtlas contains Atlas metadata about the database.

spec.mysql

MySQL is an additional section with MySQL database options.

spec.oracle

Oracle is an additional Oracle configuration options.

spec.tls

TLS is the TLS configuration used when establishing connection to target database. Allows to provide custom CA cert or override server name.

Example:

# Teleport Database

resource "teleport_database" "example" {
    metadata = {
        name = "example"
        description = "Test database"
        labels = {
            "teleport.dev/origin" = "dynamic" // This label is added on Teleport side by default
        }
    }

    spec = {
        protocol = "postgres"
        uri = "localhost"
    }
}

teleport_github_connector

metadata

Metadata holds resource metadata.

spec

Spec is an Github connector specification.

spec.teams_to_logins

TeamsToLogins maps Github team memberships onto allowed logins/roles. DELETE IN 11.0.0 Deprecated: use GithubTeamsToRoles instead.

spec.teams_to_roles

TeamsToRoles maps Github team memberships onto allowed roles.

Example:

# Terraform Github connector

variable "github_secret" {}

resource "teleport_github_connector" "github" {
  # This section tells Terraform that role example must be created before the GitHub connector
  depends_on = [
    teleport_role.example
  ]

  metadata = {
     name = "example"
     labels = {
       example = "yes"
     }
  }
  
  spec = {
    client_id = "client"
    client_secret = var.github_secret

    teams_to_roles = [{
       organization = "gravitational"
       team = "devs"
       roles = ["example"]
    }]
  }
}

teleport_login_rule

metadata

Metadata is resource metadata.

traits_map

TraitsMap is a map of trait keys to lists of predicate expressions which should evaluate to the desired values for that trait.

Example:

# Teleport Login Rule resource

resource "teleport_login_rule" "example" {
  metadata = {
    description = "Example Login Rule"
    labels = {
      "example" = "yes"
    }
  }

  version  = "v1"
  priority = 0
  traits_map = {
    "logins" = {
      values = [
        "external.logins",
        "external.username",
      ]
    }
    "groups" = {
      values = [
        "external.groups",
      ]
    }
  }
}

teleport_oidc_connector

metadata

Metadata holds resource metadata.

spec

Spec is an OIDC connector specification.

spec.claims_to_roles

ClaimsToRoles specifies a dynamic mapping from claims to roles.

Example:

# Teleport OIDC connector
# 
# Please note that OIDC connector will work in Enterprise version only. Check the setup docs:
# https://goteleport.com/docs/enterprise/sso/oidc/

variable "oidc_secret" {}

resource "teleport_oidc_connector" "example" {
  metadata = {
    name = "example"
    labels = {
      test = "yes"
    }
  }

  spec = {
    client_id = "client"
    client_secret = var.oidc_secret

    claims_to_roles = [{
      claim = "test"
      roles = ["terraform"]
    }]

    redirect_url = ["https://example.com/redirect"]
  }
}

teleport_okta_import_rule

metadata

Metadata is resource metadata

spec

Spec is the specification for the Okta import rule.

spec.mappings

Mappings is a list of matches that will map match conditions to labels.

spec.mappings.match

Match is a set of matching rules for this mapping. If any of these match, then the mapping will be applied.

Example:

# Teleport Okta Import Rule resource

resource "teleport_okta_import_rule" "example" {
  metadata = {
    description = "Example Okta Import Rule"
    labels = {
      "example" = "yes"
    }
  }

  version  = "v1"

  spec = {
    priority = 100
    mappings = [
      {
        add_labels = {
          "label1": "value1"
        }
        match = [
          {
            app_ids = ["1", "2", "3"]
          },
        ],
      },
      {
        add_labels = {
          "label2": "value2"
        }
        match = [
          {
            group_ids = ["1", "2", "3"]
          },
        ],
      },
      {
        add_labels = {
          "label3" : "value3",
        }
        match = [
          {
            group_name_regexes = ["^.*$"]
          },
        ],
      },
      {
        add_labels = {
          "label4" : "value4",
        }
        match = [
          {
            app_name_regexes = ["^.*$"]
          },
        ],
      }
    ]
  }
}

teleport_provision_token

metadata

Metadata is resource metadata

spec

Spec is a provisioning token V2 spec

spec.allow

Allow is a list of TokenRules, nodes using this token must match one allow rule to use this token.

spec.azure

Azure allows the configuration of options specific to the "azure" join method.

spec.azure.allow

Allow is a list of Rules, nodes using this token must match one allow rule to use this token.

spec.circleci

CircleCI allows the configuration of options specific to the "circleci" join method.

spec.circleci.allow

Allow is a list of TokenRules, nodes using this token must match one allow rule to use this token.

spec.gcp

GCP allows the configuration of options specific to the "gcp" join method.

spec.gcp.allow

Allow is a list of Rules, nodes using this token must match one allow rule to use this token.

spec.github

GitHub allows the configuration of options specific to the "github" join method.

spec.github.allow

Allow is a list of TokenRules, nodes using this token must match one allow rule to use this token.

spec.gitlab

GitLab allows the configuration of options specific to the "gitlab" join method.

spec.gitlab.allow

Allow is a list of TokenRules, nodes using this token must match one allow rule to use this token.

spec.kubernetes

Kubernetes allows the configuration of options specific to the "kubernetes" join method.

spec.kubernetes.allow

Allow is a list of Rules, nodes using this token must match one allow rule to use this token.

spec.kubernetes.static_jwks

StaticJWKS is the configuration specific to the static_jwks type.

spec.spacelift

Spacelift allows the configuration of options specific to the "spacelift" join method.

spec.spacelift.allow

Allow is a list of Rules, nodes using this token must match one allow rule to use this token.

Example:

# Teleport Provision Token resource

resource "teleport_provision_token" "example" {
  metadata = {
    expires = "2022-10-12T07:20:51Z"
    description = "Example token"

    labels = {
      example = "yes" 
      "teleport.dev/origin" = "dynamic" // This label is added on Teleport side by default
    }
  }

  spec = {
    roles = ["Node", "Auth"]
  }
}

resource "teleport_provision_token" "iam-token" {
  metadata = {
    name = "iam-token"
  }
  spec = {
    roles       = ["Bot"]
    bot_name    = "mybot"
    join_method = "iam"
    allow = [{
      aws_account = "123456789012"
    }]
  }
}

teleport_role

metadata

Metadata is resource metadata

spec

Spec is a role specification

spec.allow

Allow is the set of conditions evaluated to grant access.

spec.allow.db_permissions

DatabasePermissions specifies a set of permissions that will be granted to the database user when using automatic database user provisioning.

spec.allow.impersonate

Impersonate specifies what users and roles this role is allowed to impersonate by issuing certificates or other possible means.

spec.allow.join_sessions

JoinSessions specifies policies to allow users to join other sessions.

spec.allow.kubernetes_resources

KubernetesResources is the Kubernetes Resources this Role grants access to.

spec.allow.request

spec.allow.request.claims_to_roles

ClaimsToRoles specifies a mapping from claims (traits) to teleport roles.

spec.allow.request.thresholds

Thresholds is a list of thresholds, one of which must be met in order for reviews to trigger a state-transition. If no thresholds are provided, a default threshold of 1 for approval and denial is used.

spec.allow.require_session_join

RequireSessionJoin specifies policies for required users to start a session.

spec.allow.review_requests

ReviewRequests defines conditions for submitting access reviews.

spec.allow.review_requests.claims_to_roles

ClaimsToRoles specifies a mapping from claims (traits) to teleport roles.

spec.allow.rules

Rules is a list of rules and their access levels. Rules are a high level construct used for access control.

spec.allow.spiffe

SPIFFE is used to allow or deny access to a role holder to generating a SPIFFE SVID.

spec.deny

Deny is the set of conditions evaluated to deny access. Deny takes priority over allow.

spec.deny.db_permissions

DatabasePermissions specifies a set of permissions that will be granted to the database user when using automatic database user provisioning.

spec.deny.impersonate

Impersonate specifies what users and roles this role is allowed to impersonate by issuing certificates or other possible means.

spec.deny.join_sessions

JoinSessions specifies policies to allow users to join other sessions.

spec.deny.kubernetes_resources

KubernetesResources is the Kubernetes Resources this Role grants access to.

spec.deny.request

spec.deny.request.claims_to_roles

ClaimsToRoles specifies a mapping from claims (traits) to teleport roles.

spec.deny.request.thresholds

Thresholds is a list of thresholds, one of which must be met in order for reviews to trigger a state-transition. If no thresholds are provided, a default threshold of 1 for approval and denial is used.

spec.deny.require_session_join

RequireSessionJoin specifies policies for required users to start a session.

spec.deny.review_requests

ReviewRequests defines conditions for submitting access reviews.

spec.deny.review_requests.claims_to_roles

ClaimsToRoles specifies a mapping from claims (traits) to teleport roles.

spec.deny.rules

Rules is a list of rules and their access levels. Rules are a high level construct used for access control.

spec.deny.spiffe

SPIFFE is used to allow or deny access to a role holder to generating a SPIFFE SVID.

spec.options

Options is for OpenSSH options like agent forwarding.

spec.options.cert_extensions

CertExtensions specifies the key/values

spec.options.idp

IDP is a set of options related to accessing IdPs within Teleport. Requires Teleport Enterprise.

spec.options.idp.saml

SAML are options related to the Teleport SAML IdP.

spec.options.record_session

RecordDesktopSession indicates whether desktop access sessions should be recorded. It defaults to true unless explicitly set to false.

Example:

# Teleport Role resource

resource "teleport_role" "example" {
  metadata = {
    name        = "example"
    description = "Example Teleport Role"
    expires     = "2022-10-12T07:20:51Z"
    labels = {
      example  = "yes"      
    }
  }
  
  spec = {
    options = {
      forward_agent           = false
      max_session_ttl         = "7m"
      port_forwarding         = false
      client_idle_timeout     = "1h"
      disconnect_expired_cert = true
      permit_x11_forwarding   = false
      request_access          = "denied"
    }

    allow = {
      logins = ["example"]

      rules = [{
        resources = ["user", "role"]
        verbs = ["list"]
      }]

      request = {
        roles = ["example"]
        claims_to_roles = [{
          claim = "example"
          value = "example"
          roles = ["example"]
        }]
      }

      node_labels = {
        example = ["yes"]
      }
    }

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

teleport_saml_connector

metadata

Metadata holds resource metadata.

spec

Spec is an SAML connector specification.

spec.assertion_key_pair

EncryptionKeyPair is a key pair used for decrypting SAML assertions.

spec.attributes_to_roles

AttributesToRoles is a list of mappings of attribute statements to roles.

spec.signing_key_pair

SigningKeyPair is an x509 key pair used to sign AuthnRequest.

Example:

# Teleport SAML connector
# 
# Please note that SAML connector will work in Enterprise version only. Check the setup docs:
# https://goteleport.com/docs/enterprise/sso/okta/

resource "teleport_saml_connector" "example" {
  # This block will tell Terraform to never update private key from our side if a keys are managed 
  # from an outside of Terraform.

  # lifecycle {
  #   ignore_changes = [
  #     spec[0].signing_key_pair[0].cert,
  #     spec[0].signing_key_pair[0].private_key,
  #     spec[0].assertion_key_pair[0].cert,
  #     spec[0].assertion_key_pair[0].private_key,
  #   ]
  # }

  # This section tells Terraform that role example must be created before the SAML connector
  depends_on = [
    teleport_role.example
  ]

  metadata = {
    name = "example"
  }

  spec = {
    attributes_to_roles = [{
      name  = "groups"
      roles = ["example"]
      value = "okta-admin"
    },
    {
      name  = "groups"
      roles = ["example"]
      value = "okta-dev"
    }]

    acs               = "https://localhost:3025/v1/webapi/saml/acs"
    entity_descriptor = ""
  }
}

teleport_session_recording_config

metadata

Metadata is resource metadata

spec

Spec is a SessionRecordingConfig specification

Example:

# Teleport session recording config

resource "teleport_session_recording_config" "example" {
  metadata = {
    description = "Session recording config"
    labels = {
      "example" = "yes"
      "teleport.dev/origin" = "dynamic" // This label is added on Teleport side by default
    }
  }

  spec = {
    proxy_checks_host_keys = true
  }
}

teleport_trusted_cluster

metadata

Metadata holds resource metadata.

spec

Spec is a Trusted Cluster specification.

spec.role_map

RoleMap specifies role mappings to remote roles.

Example:

# Teleport trusted cluster
#
# https://goteleport.com/docs/setup/admin/trustedclusters/

resource "teleport_trusted_cluster" "cluster" {
  metadata = {
    name = "primary"
    labels = {
      test = "yes"
    }
  }

  spec = {
    enabled = false
    role_map = [{
      remote = "test"
      local = ["admin"]
    }]
    proxy_addr = "localhost:3080"
    token = "salami"
  }
}

teleport_trusted_device

metadata

Metadata is resource metadata

spec

Specification of the device.

spec.source

Example:

# Trusted device resource

resource "teleport_trusted_device" "TESTDEVICE1" {
  spec = {
    asset_tag = "TESTDEVICE1"
    os_type   = "macos"
  }
}

teleport_user

metadata

Metadata is resource metadata

spec

Spec is a user specification

spec.github_identities

GithubIdentities list associated Github OAuth2 identities that let user log in using externally verified identity

spec.oidc_identities

OIDCIdentities lists associated OpenID Connect identities that let user log in using externally verified identity

spec.saml_identities

SAMLIdentities lists associated SAML identities that let user log in using externally verified identity

Example:

# Teleport User resource

resource "teleport_user" "example" {
  # Tells Terraform that the role could not be destroyed while this user exists
  depends_on = [
    teleport_role.example
  ]

  metadata = {
    name        = "example"
    description = "Example Teleport User"

    expires = "2022-10-12T07:20:50Z"

    labels = {
      example = "yes"
    }
  }

  spec = {
    roles = ["example"]

    oidc_identities = [{
      connector_id = "oidc1"
      username     = "example"
    }]

    traits = {
      "logins1" = ["example"]
      "logins2" = ["example"]
    }

    github_identities = [{
      connector_id = "github"
      username     = "example"
    }]

    saml_identities = [{
      connector_id = "example-saml"
      username     = "example"
    }]
  }
}