# Run the Teleport Terraform Provider on a Server This guide demonstrates how to set up the Terraform provider for Teleport on a persistent Linux or macOS server. This guide does not cover running the Terraform provider locally, or in temporary environments such as CI/CD and short-lived cloud VMs. If you are in one of those cases, please follow the dedicated guides: - [Run the Terraform Provider in CI or cloud VMs](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider/ci-or-cloud.md) - [Run the Terraform Provider locally](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider/local.md) This guide will setup Teleport Machine & Workload Identity on the server. Machine & Workload Identity provides identities to machines and services, rather than human users. ## How it works This setup relies on a Machine & Workload Identity daemon (`tbot`) to join the Teleport cluster, obtain and refresh credentials for the Terraform provider. The daemon stores its identity on the disk and refresh the terraform credentials, typically every 30 minutes. ## Prerequisites - A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * [Terraform >= 1.0.0+](https://learn.hashicorp.com/tutorials/terraform/install-cli) ``` $ terraform version Terraform v1.0.0 ``` * To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.7.3 CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions. * A Linux host that you wish to run the Teleport Terraform provider onto. * A Linux user on that host that you wish Terraform and `tbot` to run as. ## Step 1/4. Install `tbot` on your server You must install `tbot` and make it join the Teleport cluster. To do so, follow [the `tbot` deployment guide for Linux](https://goteleport.com/docs/machine-workload-identity/deployment/linux.md) until step 3. ## Step 2/4. Configure RBAC At this point, `tbot` is installed and configured on the machine that will run Terraform. Starting with 16.2, Teleport comes with a built-in role for the Terraform provider: `terraform-provider`. RBAC for versions before v16.2 On older versions you will need to create the Terraform role yourself. Write the following `role.yaml` manifest: ``` kind: role version: v7 metadata: name: terraform-provider spec: allow: db_labels: '*': '*' app_labels: '*': '*' node_labels: '*': '*' rules: - resources: - app - cluster_auth_preference - cluster_networking_config - db - device - github - login_rule - oidc - okta_import_rule - role - saml - session_recording_config - token - trusted_cluster - user - access_list - node verbs: ['list','create','read','update','delete'] ``` Use `tctl create -f ./role.yaml` to create the role. Use the `tctl bots update` command to add the role to the Bot. Replace `example` with the name of the Bot you created in the deployment guide. ``` $ tctl bots update example --add-roles terraform-provider ``` ## Step 3/4. Configure `tbot` output Now, `tbot` needs to be configured with an output that will produce the credentials needed by the Terraform provider. As the Terraform provider will be accessing the Teleport API, the correct output type to use is `identity`. For this guide, the `directory` destination will be used. This will write these credentials to a specified directory on disk. Ensure that this directory can be written to by the Linux user that `tbot` runs as, and that it can be read by the Linux user that Terraform will run as. Modify your `tbot` configuration to add an `identity` output: ``` services: - type: identity destination: type: directory # For this guide, /opt/machine-id is used as the destination directory. # You may wish to customize this. Multiple outputs cannot share the same # destination. path: /opt/machine-id ``` If operating `tbot` as a background service, restart it. If running `tbot` in one-shot mode (which creates credentials and ends the process, rather than running a background process), it must be executed before you attempt to execute the Terraform plan later. You should now see an `identity` file under `/opt/machine-id`. This contains the private key and signed certificates needed by the Terraform provider to authenticate with the Teleport Auth Service. ## Step 4/4. Run Terraform Start by creating a new Terraform working directory: ``` $ mkdir ./my-terraform && cd ./my-terraform $ terraform init ``` In order to configure the Teleport Terraform provider to use the credentials output by Machine & Workload Identity, we use the `identity_file_path` option. In this directory, create `main.tf`: ``` terraform { required_providers { teleport = { version = "18.7.3" source = "terraform.releases.teleport.dev/gravitational/teleport" } } } provider "teleport" { # Replace with the address of your Teleport Proxy or Auth Service. addr = "teleport.example.com:443" # Replace with the directory configured in the identity output in the # previous step. identity_file_path = "/opt/machine-id/identity" } # We must create a test role, if we don't declare resources, Terraform won't try to # connect to Teleport and we won't be able to validate the setup. resource "teleport_role" "terraform-test" { version = "v7" metadata = { name = "terraform-test" description = "Example role created by Terraform" } spec = { # This role does nothing as it is an example role. allow = {} } } ``` Replace `teleport.example.com:443` with the address of your Teleport Proxy Service or Auth Service. If you modified the destination directory from `/opt/machine-id`, then this should also be replaced. Now, execute Terraform to test the configuration: ``` $ terraform init $ terraform plan $ terraform apply ``` Check your Teleport cluster, ensuring the role has been created: ``` $ tctl get role/terraform-test ``` ## Next steps - Explore the [Terraform provider resource reference](https://goteleport.com/docs/reference/infrastructure-as-code/terraform-provider.md) to discover what can be configured with the Teleport Terraform provider. - Read the [tbot configuration reference](https://goteleport.com/docs/reference/machine-workload-identity/configuration.md) to explore all the available `tbot` configuration options.