Terraform Provider: teleportconnect

teleportconnect provides Terraform-native, Teleport-mediated access to remote resources — database client credentials, database tunnels, and SSH tunnels — without requiring tsh, jq, or bash on the machine running Terraform.

It is the in-process equivalent of common tsh workflows:

This provider	tsh equivalent
ephemeral.teleportconnect_db_certificate	tsh db login + tsh db config
ephemeral.teleportconnect_db_tunnel	tsh proxy db --tunnel
ephemeral.teleportconnect_ssh_tunnel	tsh ssh -N -L LOCAL:TARGET GATEWAY
data.teleportconnect_database	tsh db ls
data.teleportconnect_node	tsh ls
data.teleportconnect_cluster	tsh status (cluster info + CA)

Because credentials and tunnels are modeled as ephemeral resources, the issued certificates and private keys are never written to Terraform state.

Requirements

• Terraform >= 1.12 (ephemeral resources are required)
• A reachable Teleport cluster, v15 or newer (the provider requests ECDSA P-256 user certificates, which require a modern auth server)
• Credentials for that cluster: a tsh profile, or an identity file from tctl auth sign / tbot

Using the provider

terraform {
  required_version = ">= 1.12.0"
  required_providers {
    teleportconnect = {
      source  = "cruxstack/teleportconnect"
      version = "~> 0.1"
    }
  }
}

provider "teleportconnect" {
  proxy_address     = "teleport.example.com:443"
  use_local_profile = true
}

Authentication

Exactly one authentication method must be configured:

Attribute	Description
use_local_profile	Reuse the local ~/.tsh profile for proxy_address (mirrors tsh login).
identity_file_path	Path to an identity file produced by tctl auth sign or tbot.
identity_file_data	Inline identity file contents (PEM bundle). Marked sensitive.
join_method + join_token	Delegated Machine ID join for CI — the provider joins the cluster in-process, no tbot needed.

CI / Machine ID join (no tbot, no identity file)

For non-interactive runners, set join_method + join_token. The provider fetches the platform's OIDC/JWT identity token and joins the cluster in-process — no tbot sidecar and no identity file to manage:

provider "teleportconnect" {
  proxy_address = "teleport.example.com:443"
  join_method   = "github" # github | gitlab | kubernetes | spacelift
  join_token    = "teleportconnect-ci"
}

Supported methods: github, gitlab, kubernetes, spacelift. For GitHub Actions, the only extra requirement is permissions: id-token: write on the job. See the CI usage guide and the join methods guide for per-platform setup.

Example: issue a database certificate

data "teleportconnect_database" "main" {
  name = "mycorp-postgres"
}

ephemeral "teleportconnect_db_certificate" "main" {
  database = data.teleportconnect_database.main.matched_name
  db_user  = "readonly"
  db_name  = "appdb"
}

Example: open a database tunnel

ephemeral "teleportconnect_db_tunnel" "main" {
  database = data.teleportconnect_database.main.matched_name
  db_user  = "readonly"
  db_name  = "appdb"
}

provider "postgresql" {
  host     = ephemeral.teleportconnect_db_tunnel.main.local_host
  port     = ephemeral.teleportconnect_db_tunnel.main.local_port
  database = "appdb"
  username = "readonly"
  sslmode  = "disable" # the tunnel terminates TLS to Teleport for you
}

Example: open an SSH tunnel

data "teleportconnect_node" "bastion" {
  labels = { role = "bastion" }
}

ephemeral "teleportconnect_ssh_tunnel" "db" {
  gateway_node = data.teleportconnect_node.bastion.matched_hostname
  ssh_login    = "ec2-user"
  target_host  = "internal-db.vpc.local"
  target_port  = 5432
}

See docs/ for full reference documentation and the examples/ directory for runnable configurations. For running the provider in CI (e.g. self-hosted GitHub Actions runners) against the cyrilgdn/postgresql provider, see the CI usage guide.

ALPN connection upgrade

When the Teleport proxy sits behind an L7 load balancer (e.g. AWS ALB) that terminates TLS with its own certificate, Teleport's automatic ALPN probe can be fooled into using direct TLS routing, which then fails. Set alpn_conn_upgrade = "yes" to force the HTTPS connection upgrade in that case. The default (auto) probes the proxy; no forces direct TLS routing.

Teleport RBAC

The credentials used by the provider need a role that allows, at minimum:

• reading db_server and node resources (for the data sources and protocol lookup)
• issuing user certificates scoped to the target databases / nodes and logins

See docs/guides/teleport-rbac.md for a sample role.

Developing the provider

# build
make build

# install into the local Go bin for dev_overrides
make install

# format, lint, vet
make fmt
make lint

# unit tests
make test

# acceptance tests (requires a live cluster + TF_ACC=1 + env vars)
make testacc

# regenerate registry docs from schema, examples, and templates/guides
make docs

Running against a local cluster

A single-node Teleport cluster for local acceptance/integration testing is provided under test/integration/. See its README for the bootstrap steps.

Roadmap

• Delegated Machine ID join methods (iam, github, gcp, ...) implemented directly against the Teleport JoinService, removing the need for a tbot sidecar.
• Configurable key algorithm (RSA / ECDSA / Ed25519).

License

MPL-2.0