Skip to main content
Version: 17.x

GCP Tags and Labels as Teleport Agent Labels

Report an issue with this page

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 is present, its value (must be lower case) 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 17.5.2 or above. If you do not have one, read Get Started with Teleport.

  • The tctl and tsh clients.

    Details

    Installing tctl and tsh clients

    Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

    curl -O https://cdn.teleport.dev/teleport-17.5.2.pkg

    In Finder double-click the pkg file to begin installation.

    danger

    Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

    The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/ping and use a JSON query tool to obtain your cluster version:

    curl https://example.teleport.sh/v1/webapi/ping | jq -r '.server_version'
    17.5.2
  • 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.