# GCP Tags and Labels as Teleport Agent Labels

When running on an Google Compute Engine instance, Teleport will automatically detect and import GCP [tags](https://cloud.google.com/resource-manager/docs/tags/tags-overview) (key-value pairs that are their own resource) and [labels](https://cloud.google.com/compute/docs/labeling-resources) (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. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

- 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:

     **Mac**

     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.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

* One Teleport Agent running on a GCP Compute instance. See [our guides](https://goteleport.com/docs/enroll-resources/agents.md) 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.