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

Deploying tbot on GCP

Report an Issue

This guide explains how to deploy the Machine & Workload Identity agent, tbot, on a Google Cloud Platform GCE instance and connect it to your Teleport cluster.

note

The steps in this guide provide an example configuration to help you get started. Your environment or use case may require additional or different settings. Adjust the configuration to fit your specific requirements.

How it works​

On GCP, virtual machines can be assigned a service account. These machines can then request a signed JSON web token from GCP, which allows third parties to verify information about them, including their service accounts, using the GCP public key. The Teleport gcp join method instructs tbot to use this service account JWT to prove its identity to the Teleport Auth Service and join your Teleport cluster without using long-lived secrets.

Whilst the guide on this page focuses explicitly on deploying tbot on a GCP Virtual Machine, it is also possible to use the gcp join method with workloads running on Google Kubernetes Engine. To do so, you must configure GCP Workload Identity 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. 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.

  • 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 protected] to your Teleport username: 
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status
    Cluster  teleport.example.com
    Version  19.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 GCP service account you wish to grant access to your Teleport cluster that is not the GCP compute default service account.
  • A GCP Compute Engine VM that you wish to install tbot onto that has been configured with the GCP service account.

Step 1/5. Install tbot​

This step is completed on the GCP VM.

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 a Teleport Agent on your Linux server:

The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

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

  2. Run your cluster's install script:

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

Step 2/5. 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/5. 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: gcp
  gcp:
    # allow specifies the rules by which the Auth Service determines if `tbot`
    # should be allowed to join.
    allow:
    - project_ids:
        - my-project-123456
      service_accounts:
        # This should be the full "name" of a GCP service account. The default
        # compute service account is not supported.
        - [email protected]

Replace:

  • my-project-123456 with the ID of your GCP project
  • example with the name of the bot you created in the second step.
  • [email protected] with the email of the service account configured in the previous step. The default compute service account is not supported.

Use tctl to apply this file:

tctl create -f bot-token.yaml

Step 4/5. Configure tbot​

This step is completed on the GCP VM.

Next, you'll create a file to configure tbot. In this example, we'll be configuring tbot to use the identity service. This will generate a set of short-lived certificates which can be used by tsh or tctl to authenticate to your Teleport cluster as the bot.

Create /etc/tbot.yaml:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: gcp
  token: example-bot
storage:
  type: memory
# services will be filled in during the completion of an access guide.
services:
- type: identity
  destination:
    type: directory
    path: /opt/machine-id

Replace:

  • example.teleport.sh:443 with the address of your Teleport Proxy or Auth Service. Prefer using the address of a Teleport Proxy.
  • example-bot with the name of the token you created in the second step.
  • /opt/machine-id with a path to a directory where tbot should write the short-lived credentials. Ensure that the user tbot is running and has the appropriate permissions to create this directory.

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 \   --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.

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
auth_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.

Step 5/5. Testing your tbot configuration​

tbot will now be producing a set of short-lived credentials within /opt/machine-id. To verify that is working correctly, we'll now test these credentials using tsh.

On the host where you have deployed tbot, run the following, replacing --proxy with the address of your Teleport Proxy Service and -i with the path to the identity file within your configured directory:

tsh --proxy example.teleport.sh:443 -i /opt/machine-id/identity status                                                                                                                                                                                                                                         127 ↵
> Profile URL:        https://example.teleport.sh:443Logged in as:       bot-exampleCluster:            example.teleport.shRoles:              accessLogins:             support, ubuntuKubernetes:         disabledValid until:        2025-11-12 14:08:34 +0000 GMT [valid for 58m]Extensions:         [email protected], [email protected], disallow-reissue, impersonator, login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy

You have now prepared a basic deployment of tbot for your platform, and verified that it can produce a simple output that can be used with tsh and tctl. For guidance on how to configure tbot for your use case, follow one of the access guides and replace the example identity service you configured in this guide.

Next steps​