Teleport

Automatically Discover GCP Compute Instances

Available for:
OpenSource
Team
Cloud
Enterprise

The Teleport Discovery Service can connect to GCP and automatically discover and enroll GCP Compute Engine instances matching configured labels. It will then execute a script on these discovered instances that will install Teleport, start it and join the cluster.

Prerequisites

A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
The tctl admin tool and tsh client tool version >= 14.0.1.

See Installation for details.

A Teleport Team account. If you don't have an account, sign up to begin your free trial.
The Enterprise tctl admin tool and tsh client tool, version >= 13.3.9.

You can download these tools from the Cloud Downloads page.

A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 14.0.1.

You can download these tools by visiting your Teleport account workspace.

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21

tsh version
Teleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com

A GCP compute instance to run the Discovery Service on.
GCP compute instances to join the Teleport cluster, running Ubuntu/Debian/RHEL if making use of the default Teleport install script. (For other Linux distributions, you can install Teleport manually.)
To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:
```
tsh login --proxy=teleport.example.com --user=[email protected]
tctl status
Cluster  teleport.example.com
Version  14.0.1
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.

Step 1/6. Create a GCP invite token

When discovering GCP compute instances, Teleport makes use of GCP invite tokens for authenticating joining SSH Service instances.

Create a file called token.yaml:

# token.yaml
kind: token
version: v2
metadata:
  # the token name is not a secret because instances must prove that they are
  # running in your GCP project to use this token
  name: gcp-discovery-token
spec:
  # use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop)
  roles: [Node]

  # set the join method allowed for this token
  join_method: gcp

  gcp:
    allow:
      # The GCP project ID(s) that VMs can join from.
      - project_ids: []
        # (Optional) The locations that VMs can join from. Note: both regions and
        # zones are accepted.
        locations: []
        # (Optional) The email addresses of service accounts that VMs can join
        # with.
        service_accounts: []

Add your instance's project ID(s) to the project_ids field. Add the token to the Teleport cluster with:

tctl create -f token.yaml

Step 2/6. Configure IAM permissions for Teleport

Create a service account that will give Teleport IAM permissions needed to discover instances.

Go to IAM > Roles in the GCP console and click + Create Role. Pick a name for the role (e.g. teleport-discovery) and give it the following permissions:

compute.instances.get
compute.instances.getGuestAttributes
compute.instances.list
compute.instances.setMetadata

Click Create.

Go to IAM > Service accounts and click + Create Service Account. Pick a name for the service account (e.g. teleport-discovery) and copy its email address to your clipboard. Click Create and Continue.

Go to IAM and click Grant Access. Paste the service account's email into the New principals field and select your custom role. Click Save.

Copy the following and paste it into a file called teleport-discovery-role.yaml:

# teleport-discovery-role.yaml
title: "teleport-discovery"
description: "A role to enable Teleport to discover GCP compute instances"
stage: "ALPHA"
includedPermissions:
- compute.instances.get
- compute.instances.getGuestAttributes
- compute.instances.list
- compute.instances.setMetadata

Then run the following command to create the role:

gcloud iam roles create teleport_discovery \--project=project_id \--file=teleport-discovery-role.yaml

Run the following command to create the service account:

gcloud iam service-accounts create teleport-discovery \--description="A service account to enable Teleport to discover GCP compute instances" \--display-name="teleport-discovery"

Run the following command to add the new role to the new service account:

gcloud projects add-iam-policy-binding project_id \--member="serviceAccount:teleport-discovery@project_id.iam.gserviceaccount.com" \--role="projects/project_id/role/teleport_discovery"

Step 3/6. Configure instances to be discovered

Ensure that each instance to be discovered has a service account assigned to it. No permissions are required on the service account. To check if an instance has a service account, run the following command and confirm that there is at least one entry under serviceAccounts:

gcloud compute instances describe --format="yaml(name,serviceAccounts)" instance_name

Enable guest attributes on instances

Guest attributes (a subset of custom metadata used for infrequently updated data) must be enabled on instances to be discovered so Teleport can access their SSH host keys. Enable guest attributes by setting enable-guest-attributes to TRUE in the instance's metadata.

gcloud compute instances add-metadata instance_name \--metadata=enable-guest-attributes=True

If guest attributes are enabled during instance creation, the guest attributes will automatically be populated with the instance's host keys. If guest attributes were enabled after the instance was created, you can manually add the host keys to the guest attributes below:

Create a file named add-host-keys.sh and copy the following into it:

#!/usr/bin/env bash
for file in /etc/ssh/ssh_host_*_key.pub
  do
  KEY_TYPE=$(awk '\''{print $1}'\'' $file)
  KEY=$(awk '\''{print $2}'\''  $file)
  curl -X PUT --data "$KEY" "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/hostkeys/$KEY_TYPE" -H "Metadata-Flavor: Google"
done

Run the following command to add the host keys as part of a startup script:

gcloud compute instances add-metadata instance_name \--metadata-from-file=startup-script="add-host-keys.sh"

Run the following command to add the host keys over SSH:

gcloud compute ssh instance_name \--command='for file in /etc/ssh/ssh_host_*_key.pub; do KEY_TYPE=$(awk '\''{print $1}'\'' $file); KEY=$(awk '\''{print $2}'\''  $file); curl -X PUT --data "$KEY" "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/hostkeys/$KEY_TYPE" -H "Metadata-Flavor: Google"; done'

Step 4/6. Install the Teleport Discovery Service

Tip

If you plan on running the Discovery Service on a host that is already running another Teleport service (Auth or Proxy, for example), you can skip this step.

Install Teleport on the virtual machine that will run the Discovery Service.

Select an edition, then follow the instructions for that edition to install Teleport.

Teleport Edition

curl https://goteleport.com/static/install.sh | bash -s 14.0.1

Add the Teleport repository to your repository list:

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"
sudo yum install teleport-ent-updater
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

Install teleport
sudo dnf install teleport-ent-updater

Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent-updater

OS repository channels

The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v14 anywhere in the Teleport documentation.

Channel name	Description
`stable/<major>`	Receives releases for the specified major release line, i.e. `v14`
`stable/cloud`	Rolling channel that receives releases compatible with current Cloud version
`stable/rolling`	Rolling channel that receives all published Teleport releases

Before installing a teleport binary with a version besides v13, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.

When running multiple teleport binaries within a cluster, the following rules apply:

Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
Servers support clients that are 1 major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service is compatible with 7.x.x resource services and 7.x.x tsh, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
Proxy Services and resource services do not support Auth Services that are on an older major version, and will fail to connect to older Auth Services by default. This behavior can be overridden by passing --skip-version-check when starting Proxy Services and resource services.

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v14. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v14" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent