Skip to main content

GCP Tags and Labels as Teleport Agent Labels

When running on an Google Compute Engine instance, Teleport will automatically detect and import GCP tags (key-value pairs that are their own resource) and labels (key-value pairs that are specific to each instance) as Teleport labels for SSH nodes, applications, databases, and Kubernetes clusters. Both tags and labels imported this way will have the gcp/ prefix; additionally, tags will receive the tag/ infix and labels will receive the label/ infix. For example, an instance with label foo=bar and tag baz=quux will have the Teleport labels gcp/label/foo=bar and gcp/tag/baz=quux.

When the Teleport process starts, it fetches all tags and labels from the GCP API and adds them as labels. The process will update the tags every hour, so newly created or deleted tags will be reflected in the labels.

If the GCP label TeleportHostname (case-sensitive) is present, its value will override the node's hostname. This does not apply to GCP tags.

$ tsh ls
Node Name            Address        Labels                                                                                                                  
-------------------- -------------- -------------------------------------------------------------------------------------------
fakehost.example.com 127.0.0.1:3022 gcp/label/testing=yes,gcp/tag/environment=staging,gcp/TeleportHostname=fakehost.example.com
note

For services that manage multiple resources (such as the Database Service), each resource will receive the same tags and labels from GCP.

Prerequisites​

  • A running Teleport cluster version 15.4.22 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 and tsh client tool.

    On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

  • One Teleport agent running on a GCP Compute instance. See our guides for how to set up Teleport agents.

Configure service account on instances with Teleport nodes​

Create a service account that will give Teleport the IAM permissions needed to import tags and labels. Copy the following and paste it into a file called teleport-labels-role.yaml:

# teleport-labels-role.yaml
title: "teleport-labels"
description: "A role to enable Teleport to import tags and labels"
stage: "ALPHA"
includedPermissions:
- compute.instances.get
- compute.instances.listEffectiveTags

Then run the following command to create the role:

$ gcloud iam roles create teleport_labels \
--project=project_id \
--file=teleport-labels-role.yaml

Run the following command to create the service account:

$ gcloud iam service-accounts create teleport-labels \
--description="A service account to enable Teleport to import tags and labels" \
--display-name="teleport-labels"

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-labels@project_id.iam.gserviceaccount.com" \
--role="projects/project_id/roles/teleport_labels"

If you want to only import labels or only import tags, you can leave compute.instances.listEffectiveTags or compute.instances.get out of your created service account's permissions, respectively.