Skip to main content
Version: 19.x (unreleased)

Teleport MWI Terraform Provider

Report an Issue

The Teleport MWI Terraform provider generates short-lived credentials using Teleport Machine & Workload Identity (MWI) that can be used to grant other Terraform providers access to resources.

To manage the configuration of Teleport itself, use the Teleport Terraform Provider instead.

Example usage​

In this example, we will use the Teleport MWI Terraform provider to grant the Kubernetes provider access to a Kubernetes cluster through Teleport.

Our Kubernetes cluster is enrolled in Teleport under the name my-cluster, and we've setup a Bot and Join Token to allow our Terraform provider to authenticate to Teleport.

terraform {
  required_providers {
    teleportmwi = {
      source = "terraform.releases.teleport.dev/gravitational/teleportmwi"
      version = "~> 19.0"
    }
    kubernetes = {
      source = "hashicorp/kubernetes"
    }
  }
}

provider "teleportmwi" {
  join_method = "gitlab"
  join_token = "my-join-token"
  proxy_server = "example.teleport.sh:443"
}

ephemeral "teleportmwi_kubernetes" "my_cluster" {
  selector = {
    name = "my-cluster"
  }
}


// https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs
provider "kubernetes" {
  host                   = ephemeral.teleportmwi_kubernetes.my_cluster.output.host
  tls_server_name        = ephemeral.teleportmwi_kubernetes.my_cluster.output.tls_server_name
  client_certificate     = ephemeral.teleportmwi_kubernetes.my_cluster.output.client_certificate
  client_key             = ephemeral.teleportmwi_kubernetes.my_cluster.output.client_key
  cluster_ca_certificate = ephemeral.teleportmwi_kubernetes.my_cluster.output.cluster_ca_certificate
}

resource "kubernetes_namespace" "ns" {
  metadata {
    name = "example-namespace"
  }
}

Ephemeral resources vs data sources​

Use of data sources in the MWI Terraform provider for resources that store secrets is deprecated.

Ephemeral resources are supported by Terraform 1.10 or OpenTofu 1.11.0 and later. They have the following benefits over data sources:

  • The short-lived credentials generated by the MWI Terraform provider will not be persisted within the Terraform state.
  • Fresh short-lived credentials will be generated in the apply phase, allowing you to grant read-only privileges to plan runs and read-write privileges to apply runs.

Versions of Terraform older than 1.10 or OpenTofu 1.11.0 do not support ephemeral resources. The Kubernetes data source is deprecated and will be removed in Teleport v20. We also highly recommend that you encrypt your Terraform state file if you use it. You will also need to configure a credential_ttl that will ensure that credentials generated during the plan phase will still be valid during the apply phase.

Schema​

Required​

  • join_method (String) The join method to use to authenticate to the Teleport cluster.
  • join_token (String) The name of the join token to use to authenticate to the Teleport cluster.
  • proxy_server (String) The address of the Teleport Proxy service. This should exclude the scheme but should include the port.

Optional​

  • insecure (Boolean) When enabled, the certificates of the Proxy will not be verified. This is not recommended for production use.
  • skip_initial_connection (Boolean) When enabled, puts the provider into a lazy initialization mode where we avoid making connections to the Teleport cluster until the first resource or data source is actually used.

This can be useful in scenarios where multiple providers are at play and the user wishes to selectively use the Teleport provider.