![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Deploying Machine ID on GCP
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
This guide explains how to deploy Machine ID on Google Cloud Platform (GCP) by
running the tbot
binary and joining it to your Teleport cluster.
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 a Machine ID bot 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 Machine ID 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 Machine ID as a workload on Kubernetes.
Prerequisites
-
A running Teleport cluster version 16.2.1 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
-
The
tctl
admin tool andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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 Machine ID 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 ID
on.
Download and install the appropriate Teleport package for your platform:
Install Teleport on your Linux server:
-
Assign edition to one of the following, depending on your Teleport edition:
Edition Value Teleport Enterprise Cloud cloud
Teleport Enterprise (Self-Hosted) enterprise
Teleport Community Edition oss
-
Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:
TELEPORT_DOMAIN=example.teleport.comTELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"Otherwise, get the version of your Teleport cluster:
TELEPORT_DOMAIN=example.teleport.comTELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')" -
Install Teleport on your Linux server:
curl https://cdn.teleport.dev/install-v16.2.1.sh | bash -s ${TELEPORT_VERSION} editionThe installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.
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 Server 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 projectexample
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.
Create /etc/tbot.yaml
:
version: v2
proxy_server: example.teleport.sh:443
onboarding:
join_method: gcp
token: example-bot
storage:
type: memory
# outputs will be filled in during the completion of an access guide.
outputs: []
Replace:
example.teleport.sh:443
with the address of your Teleport Proxy or Auth Server. Prefer using the address of a Teleport Proxy.example-bot
with the name of the token you created in the second step.
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. 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:
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 runtbot
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-reloadsudo systemctl enable tbotsudo systemctl start tbot
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=1tbot 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. Configure outputs
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.
Follow one of the access guides to configure an output that meets your access needs.
Next steps
- Follow the access guides to finish configuring
tbot
for your environment. - Read the configuration reference to explore all the available configuration options.
- More information about
TELEPORT_ANONYMOUS_TELEMETRY
.