Run the Teleport Terraform Provider on Spacelift

You can use Spacelift with the Teleport Terraform provider to manage dynamic configuration resources via GitOps and infrastructure as code. This gives you an audit trail of changes to your Teleport configuration and a single source of truth for operators to examine.

This guide shows you how to use the Machine ID agent, tbot, to allow the Teleport Terraform provider running in a Spacelift stack to configure your Teleport cluster.

In this setup, tbot proves its identity to the Teleport Auth Service by presenting an ID token signed by Spacelift. This allows tbot to authenticate with the Teleport cluster without the need for a long-lived shared secret.

While following this guide, you will create a Teleport user and role with no privileges in order to show you how to use Spacelift to create dynamic resources.

Prerequisites

• A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial.

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• 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:

  $ tsh login --proxy=teleport.example.com --user=email@example.com
  $ tctl status
  # Cluster  teleport.example.com
  # Version  17.0.0-dev
  # 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 GitHub repository where you will store your Terraform configuration and a Spacelift stack linked to this repository.
• A paid Spacelift account. This is required to use the spacelift join method.
• Your Teleport user should have the privileges to create token resources.

Step 1/3. Create a role and Machine ID bot

First, we'll create a Machine ID Bot for our Spacelift job to act as. We'll grant it the terraform-provider role, which automatically grants access to every resource supported by the Teleport terraform provider.

Create bot.yaml:

kind: bot
version: v1
metadata:
  # name is a unique identifier for the Bot in the cluster.
  name: example
spec:
  # The terraform-provider is a default role shipped in Teleport granting access
  # to every resource supported by the terraform provider.
  roles:
    - terraform-provider

Make sure you replace example with a unique, descriptive, name for your Bot.

Use tctl to apply this file:

$ tctl create bot.yaml

Step 2/3. Create a join token for Spacelift

In order to allow your Spacelift stack to authenticate with your Teleport cluster, you'll first need to create a join token. A join token sets out criteria by which the Teleport Auth Service decides whether to allow a bot or node to join a cluster.

In this example, you will create a join token that grants access to any execution within a specific Spacelift stack.

Create a file named bot-token.yaml:

kind: token
version: v2
metadata:
  name: example-bot
spec:
  # The Bot role indicates that this token grants access to a bot user, rather
  # than allowing a node to join. This role is built in to Teleport.
  roles: [Bot]
  join_method: spacelift
  # The bot_name indicates which bot user this token grants access to. This
  # should match the name of the bot that you created in the previous step.
  bot_name: example
  spacelift:
    # hostname should be the hostname of your Spacelift tenant.
    hostname: example.app.spacelift.io
    # allow specifies rules that control which Spacelift executions will be
    # granted access. Those not matching any allow rule will be denied.
    allow:
    # space_id identifies the space that the module or stack resides within.
    - space_id: root
      # caller_type is the type of caller_id. This must be `stack` or `module`.
      caller_type: stack
      # caller_id is the id of the caller. e.g the name of the stack or module.
      caller_id: my-stack

Replace:

• example.app.spacelift.io with the hostname of your Spacelift tenant.
• my-stack with the name of the Spacelift stack.
• root with the ID of the space that the stack resides within. The "space details" panel on the "Spaces" page of the Spacelift UI shows the ID.

Once the resource file has been written, create the token with tctl:

$ tctl create -f bot-token.yaml

Check that token example-bot has been created with the following command:

$ tctl tokens ls
Token       Type Labels Expiry Time (UTC)
----------- ---- ------ ----------------------------------------------
example-bot Bot

Step 3/3. Configure your Spacelift stack

While following this step, you will modify your git repo to:

• Configure Spacelift to authenticate the Teleport Terraform provider as a bot user using credentials generated by Machine ID.
• Create dynamic Teleport resources using your git repo.

Before continuing, clone your GitHub repository. In the clone, check out a branch from your main branch.

Configure Spacelift to authenticate as a bot user

Now that the bot has been successfully created, you now need to configure your Spacelift stack to authenticate as this bot using tbot and then configure the Terraform provider to use the credentials produced by tbot.

To help with this, Teleport publishes a custom Spacelift container image. This image is based on the default image provided by Spacelift but additionally includes tbot.

Within the repository linked to your Spacelift stack, create .spacelift/config.yaml to specify the teleport-spacelift-runner image and to include a before_init step that invokes tbot to produce credentials:

version: "1"
stack_defaults:
  runner_image: public.ecr.aws/gravitational/teleport-spacelift-runner:17.0.0-dev
  before_init:
  - |-
    tbot start --oneshot \
      --data-dir=memory:// \
      --proxy-server teleport.example.com:443 \
      --join-method spacelift \
      --token example-bot \
      --destination-dir=/mnt/workspace/tbot-output

Replace:

• teleport.example.com:443 with the address of your Teleport cluster.
• example-bot with the name of the token you created in the first step.

Using multiple stacks in one repository?

If you have multiple Spacelift stacks within a single repository, you should note that using stack_defaults will apply this configuration to all the stacks within the repository.

To avoid this, you can use the stacks key instead of stack_defaults to configure a specific stack. See the Spacelift Runtime configuration documentation for more information.

Declare configuration resources

Add the following to a file called main.tf to configure the Teleport Terraform provider and declare two dynamic resources, a user and role:

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

provider "teleport" {
  addr               = "teleport.example.com:443"
  identity_file_path = "/mnt/workspace/tbot-output/identity"
}

resource "teleport_role" "terraform_test" {
  version = "v7"
  metadata = {
    name        = "terraform-test"
    description = "Terraform test role"
    labels = {
      test = "true"
    }
  }
}

resource "teleport_user" "terraform-test" {
  metadata = {
    name        = "terraform-test"
    description = "Terraform test user"

    labels = {
      test = "true"
    }
  }

  spec = {
    roles = [teleport_role.terraform_test.id]
  }
}

In the provider block, change teleport.example.com:443 to the host and HTTPS port of your Teleport Proxy Service.

Commit your changes and push the branch to GitHub, then open a pull request against the main branch. (Do not merge it just yet.)

Verify that the setup is working

In the Spacelift UI, navigate to your stack, then to PRs. Click the name of the PR you opened.

You should see a Terraform plan that includes the user and role you defined earlier:

When running terraform plan, Spacelift uses the identity file generated by tbot to authenticate to Teleport.

Merge the PR, then navigate to your stack and click Runs. Click the status of the first run, which corresponds to merging your PR, to visit the page for the run. Click Confirm to begin applying your Terraform plan.

You should see output indicating success:

Verify that Spacelift has created the new user and role by running the following commands, which should return YAML data for each resource:

$ tctl get roles/terraform-test
$ tctl get users/terraform-test

Next steps

• Now that you know how to manage Teleport configuration resources with Terraform and Spacelift, read the Terraform resource reference so you can flesh out your configuration.
• To find out more about Spacelift's OIDC implementation, which Machine ID uses to authenticate to your Teleport cluster, read the Spacelift documentation.
• Learn how you can help achieve secure access for service accounts by sending anonymous Machine ID telemetry.