Skip to main content
Version: 18.x

Teleport MWI Terraform Provider

Report an issue with this page

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 = "~> 18.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​

The MWI Terraform provider exposes functionality using two different kinds of entity in the Terraform ecosystem: ephemeral resources and data sources.

Ephemeral resources are supported by Terraform 1.10 and later, and should be the preferred way to use the MWI Terraform provider. 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.

When using a version of Terraform that does not support ephemeral resources, you can use the data source variants instead. When using the data sources, keep the following in mind:

  • The short-lived secrets generated by the MWI Terraform provider will be persisted within the Terraform state. The secrets will be generated in the plan phase and reused in the apply phase. We therefore highly recommend that you encrypt your Terraform state file.
  • You will 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.