Join Services with GCP
- Available for:
This guide will explain how to use the GCP join method to configure Teleport processes to join your Teleport cluster without sharing any secrets when they are running in a GCP VM.
The GCP join method is available to any Teleport process running on a GCP VM. The VM must have a service account assigned to it (the default service account is fine). No IAM roles are required on the Teleport process joining the cluster.
- A GCP VM to host a Teleport service, with a service account assigned to it and with the Teleport binary installed.
- To check that you can connect to your Teleport cluster, sign in with
tsh login, then verify that you can run
tctlcommands using your current credentials.
tctlis supported on macOS and Linux machines. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl status
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl statuscommand, you can use your current credentials to run subsequent
tctlcommands from your workstation. If you host your own Teleport cluster, you can also run
tctlcommands on the computer that hosts the Teleport Auth Service for full permissions.
Configure your Teleport Auth Service with a special dynamic token which will allow services from your GCP projects to join your Teleport cluster.
Under the hood, services will prove that they are running in your GCP project by sending a signed ID token which matches an allow rule configured in your GCP joining token.
Create the following
token.yaml file with a
gcp.allow rule specifying your GCP
project ID(s), service account(s), and location(s) in which your GCP instances
# the token name is not a secret because instances must prove that they are
# running in your GCP project to use this token
# use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop)
# set the join method allowed for this token
# The GCP project ID(s) that VMs can join from.
- project_ids: ["example-project-id"]
# (Optional) The locations that VMs can join from. Note: both regions and
# zones are accepted.
locations: ["us-west1", "us-west2-a"]
# (Optional) The email addresses of service accounts that VMs can join
service_accounts: ["[email protected]"]
Run the following command to create the token:
tctl create token.yaml
The GCP join method can be used for Teleport processes running the SSH (
Kubernetes, Application, Database, or Windows Desktop Services. The Teleport
process should be run directly on a GCP VM.
Configure your Teleport process with a custom
teleport.yaml file. Use the
join_params section with
token_name matching your token created in Step 1
method: gcp as shown in the following example config:
Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.
You can check the status of your Teleport instance with
systemctl status teleport
and view its logs with
journalctl -fu teleport.
Once you have started Teleport, confirm that your service is able to connect to and join your cluster.