![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Join Services with GCP
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
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.
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
.
- 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 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.
Step 1/3. Create the GCP joining token
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
will run:
# 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-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: ["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
# with.
service_accounts: ["[email protected]"]
Run the following command to create the token:
tctl create token.yaml
Step 2/3. Configure your services
The GCP join method can be used for Teleport processes running the SSH (Node
), Proxy,
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
and method: gcp
as shown in the following example config:
# /etc/teleport.yaml
version: v3
teleport:
join_params:
token_name: gcp-token
method: gcp
proxy_server: https://teleport.example.com:443
ssh_service:
enabled: yes
auth_service:
enabled: no
proxy_service:
enabled: no
Step 3/3. Launch your Teleport process
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.
On the host where you will run your Teleport instance, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleport
On the host where you will run your Teleport instance, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo systemctl start teleport
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.