Skip to main content

GCP Tags and Labels as Teleport Agent Labels

Report an Issue

In this guide, you will configure your Teleport cluster to assign labels to Teleport Agents running on Google Compute Engine based on their Google Cloud tags.

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 accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. 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/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install 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-${TELEPORT_VERSION?}.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.

    Connecting with TLS routing disabled

    This guide's commands assume your Teleport cluster uses TLS routing (proxy_listener_mode: multiplex), where the tctl and tsh clients reach every Teleport service through the Proxy Service's web address on port 443. If you're not sure whether this applies to your cluster, check with whoever manages it.

    If your cluster uses separate listener ports instead, adjust ports as follows:

    • tsh commands (e.g., tsh login --proxy=...): continue using the Proxy Service web address on port 3080 (or 443 if behind a load balancer). Do not change these to port 3025.

    • Direct tctl or Auth Service API commands: use port 3025 for the Auth Service gRPC listener:

      tctl status --auth-server=teleport.example.com:3025
  • One Teleport Agent running on a GCP Compute instance. See our guides for how to set up Teleport Agents.

Step 1/3. Create the IAM role and service account​

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

First, discover your project ID:

gcloud config get-value project

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.

Step 2/3. Attach the service account to your instance​

The Teleport Agent must run on an instance that has the teleport-labels service account attached. Without this attachment, the agent cannot call the GCP APIs needed to fetch tags and labels.

warning

Attaching or changing a service account on an existing VM requires stopping the VM first. Plan for a brief interruption.

Stop the instance, attach the service account, and restart it:

gcloud compute instances stop instance_name \  --zone=zone
gcloud compute instances set-service-account instance_name \  --service-account=teleport-labels@project_id.iam.gserviceaccount.com \  --scopes=cloud-platform \  --zone=zone
gcloud compute instances start instance_name \  --zone=zone

Checkpoint:

Verify that the service account is attached to the instance.

Run the following command and confirm the output shows the teleport-labels service account:

gcloud compute instances describe instance_name \  --zone=zone \  --format="yaml(serviceAccounts)"

Expected output:

serviceAccounts:
- email: teleport-labels@<project_id>.iam.gserviceaccount.com
  scopes:
  - https://www.googleapis.com/auth/cloud-platform

If the serviceAccounts field is empty or shows a different account, repeat the steps above.

You can reach out to our Slack community or customer support for help.

Step 3/3. Verify labels appear in Teleport​

After attaching the service account, restart the Teleport Agent on the instance so it picks up the new credentials:

sudo systemctl restart teleport

Wait a moment for the agent to start and fetch labels from the GCP API, then verify that GCP labels and tags are visible:

tsh ls --format=json | jq '.[].metadata.labels | with_entries(select(.key | startswith("gcp/")))'

You can also verify the labels on a specific node:

tctl get nodes --format=json | jq '.[] | select(.spec.hostname == "instance_name") | .metadata.labels'

To confirm which labels and tags are set on the GCP instance itself:

gcloud compute instances describe instance_name \  --zone=zone \  --format="yaml(labels,tags)"

Checkpoint:

Verify that GCP labels appear as Teleport labels on the node.

Run the following command:

tsh ls

The output should show labels prefixed with gcp/label/ and gcp/tag/ for your instance. For example:

Node Name            Address        Labels
-------------------- -------------- ---------------------------------------------------------
myhost.example.com   127.0.0.1:3022 gcp/label/env=prod,gcp/tag/team=platform

If no gcp/ labels appear:

  • Confirm the service account is attached (Step 2).
  • Check that the Teleport Agent process restarted after the service account was attached.
  • Review the Teleport Agent logs for permission errors:
sudo journalctl -u teleport --grep "gcp\|label" --since "5 minutes ago" --no-pager

You can reach out to our Slack community or customer support for help.