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

Deploying tbot on AWS

Report an Issue

This guide shows you how to deploy Machine & Workload Identity's agent, tbot, on an AWS EC2 instance and connect it to your Teleport cluster.

How it works​

On AWS, virtual machines can be assigned an IAM role, which they can assume in order to request a signed document that includes information about the machine.

The Teleport iam join method instructs the Machine & Workload Identity bot to request this signed document from AWS using the assigned identity and send it to the Teleport Auth Service for verification. This allows the bot to join the cluster without the exchange of a long-lived secret.

While this guide focuses on deploying tbot on an EC2 instance, it is also possible to use the iam join method with workloads running on an EKS Kubernetes cluster. To do so, you must configure IAM Roles for Service Accounts (IRSA) for the cluster and the Kubernetes service account that will be used by the tbot pod. See the Kubernetes platform guide for further guidance on deploying tbot as a workload on Kubernetes.

Prerequisites​

  • A running Teleport cluster accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

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

      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.

    Connecting with TLS routing disabled

    This guide's commands assume your Teleport cluster uses TLS routing (proxy_listener_mode: multiplex), where the tctl and tsh clients reach every Teleport service through the Proxy Service's web address on port 443. If you're not sure whether this applies to your cluster, check with whoever manages it.

    If your cluster uses separate listener ports instead, adjust ports as follows:

    • tsh commands (e.g., tsh login --proxy=...): continue using the Proxy Service web address on port 3080 (or 443 if behind a load balancer). Do not change these to port 3025.

    • Direct tctl or Auth Service API commands: use port 3025 for the Auth Service gRPC listener:

      tctl status --auth-server=teleport.example.com:3025
  • Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.

    1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.

    2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

      In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:

      tsh login --proxy=teleport.example.com --user=[email protected]
      tctl status
      Cluster  teleport.example.com
      Version  19.0.0-dev
      CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

      On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.

      When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:

      tctl status --auth-server=teleport.example.com:443

      For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:

      tsh status --proxy=teleport.example.com

      Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

      export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"

      Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.

    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.
  • An AWS IAM role that you wish to grant access to your Teleport cluster. This role must be granted sts:GetCallerIdentity. In this guide, this role will be named teleport-bot-role.
  • An AWS EC2 virtual machine that you wish to install tbot onto configured with the IAM role attached.

Step 1/4. Install tbot​

This step is completed on the AWS EC2 instance.

First, tbot needs to be installed on the VM that you wish to use Machine & Workload Identity on.

Download and install the appropriate Teleport package for your platform:

To install Teleport binaries on your Linux server, the recommended installation method is the cluster install script. This script is served by your Teleport cluster's Proxy Service and automatically selects the correct version, edition, and installation mode to match your cluster.

  1. Remove any existing Teleport binaries on your system:

    sudo rm -f /usr/local/bin/{tsh,teleport,tctl,tbot,fdpass-teleport,teleport-update}

  2. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https://).

  3. Run your cluster's install script:

    curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash

Step 2/4. Create a Bot​

This step is completed on your local machine.

Next, you need to create a Bot. A Bot is a Teleport identity for a machine or group of machines. Like users, bots have a set of roles and traits which define what they can access.

Create bot.yaml:

kind: bot
version: v1
metadata:
  # name is a unique identifier for the Bot in the cluster.
  name: example
spec:
  # roles is a list of roles to grant to the Bot. Don't worry if you don't know
  # what roles you need to specify here, the Access Guides will walk you through
  # creating and assigning roles to the already created Bot.
  roles: []

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

Use tctl to apply this file:

tctl create bot.yaml

Step 3/4. Create a join token​

This step is completed on your local machine.

Create bot-token.yaml:

kind: token
version: v2
metadata:
  # name will be specified in the `tbot` to use this token
  name: example-bot
spec:
  roles: [Bot]
  # bot_name should match the name of the bot created earlier in this guide.
  bot_name: example
  join_method: iam
  # Restrict the AWS account and (optionally) ARN that can use this token.
  # This information can be obtained from running the
  # "aws sts get-caller-identity" command from the CLI.
  allow:
    - aws_account: "111111111111"
      aws_arn: "arn:aws:sts::111111111111:assumed-role/teleport-bot-role/i-*"

Replace:

  • 111111111111 with the ID of your AWS account.
  • teleport-bot-role with the name of the AWS IAM role you created and assigned to the EC2 instance.
  • example with the name of the bot you created in the second step.
  • i-* indicates that any instance with the specified role can use the join method. If you wish to restrict this to an individual instance, replace i-* with the full instance ID.

Use tctl to apply this file:

tctl create -f bot-token.yaml

Step 4/4. Configure tbot​

This step is completed on the AWS EC2 instance.

Create /etc/tbot.yaml:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: iam
  token: example-bot
storage:
  type: memory
# services will be filled in during the completion of an access guide.
services: []

Replace:

  • example.teleport.sh:443 with the address of your Teleport Proxy Service or Auth Service. Prefer using the address of a Teleport Proxy Service instance.
  • example-bot with the name of the token you created in the third step.
warning

If your Teleport Proxy Service uses a self-signed TLS certificate, tbot output services that contact the proxy (such as the identity service) will fail to generate some files (for example, ssh_config and known_hosts). Add the proxy certificate to the system CA trust store, or configure ACME or a valid TLS certificate for your Proxy Service.

Now, you must decide if you want to run tbot as a daemon or in one-shot mode.

In daemon mode, tbot runs continually, renewing the short-lived credentials for the configured outputs on a fixed interval. This is often combined with a service manager (such as systemd) in order to run tbot in the background. This is the default behaviour of tbot.

In one-shot mode, tbot generates short-lived credentials and then exits. This is useful when combining tbot with scripting (such as in CI/CD) as it allows further steps to be dependent on tbot having succeeded. It is important to note that the credentials will expire if not renewed and to ensure that the TTL for the certificates is long enough to cover the length of the CI/CD job.

Configuring tbot as a daemon​

By default, tbot will run in daemon mode. However, this must then be configured as a service within the service manager on the Linux host. The service manager will start tbot on boot and ensure it is restarted if it fails.

If tbot was installed using the Teleport install script or teleport-update command, the tbot systemd service is automatically created for you.

After tbot.yaml is created, enable and start the service:

sudo systemctl enable tbot --now

Check the service has started successfully:

sudo systemctl status tbot

Service properties like User and Group may be configured using systemctl edit tbot.

If tbot was installed manually, service configuration will need to be performed manually as well.

For this guide, systemd will be demonstrated but tbot should be compatible with all common alternatives.

Use tbot install systemd to generate a systemd service file:

sudo tbot install systemd \   --write \   --config /etc/tbot.yaml \   --user teleport \   --group teleport \   --pid-file /run/tbot.pid \   --anonymous-telemetry

Ensure that you replace:

  • teleport with the name of Linux user you wish to run tbot as.
  • /etc/tbot.yaml with the path to the configuration file you have created.
  • /run/tbot.pid with a path that the user configured for tbot has write access to. By default, tbot writes its PID file to /run/tbot.pid.

You can omit --write to print the systemd service file to the console instead of writing it to disk.

--anonymous-telemetry enables the submission of anonymous usage telemetry. This helps us shape the future development of tbot. You can disable this by omitting this.

Next, enable the service so that it will start on boot and then start the service:

sudo systemctl daemon-reload
sudo systemctl enable tbot --now

Check the service has started successfully:

sudo systemctl status tbot

Configuring tbot for one-shot mode​

To use tbot in one-shot mode, modify /etc/tbot.yaml to add oneshot: true:

version: v2
oneshot: true
proxy_server: ...

Now, you should test your tbot configuration. When started, several log messages will be emitted before it exits with status 0:

export TELEPORT_ANONYMOUS_TELEMETRY=1
tbot start -c /etc/tbot.yaml

TELEPORT_ANONYMOUS_TELEMETRY enables the submission of anonymous usage telemetry. This helps us shape the future development of tbot. You can disable this by omitting this.

Next steps​

You have now prepared the base configuration for tbot. At this point, it identifies itself to the Teleport cluster and renews its own credentials but does not output any credentials for other applications to use.