# Join Services with GCP

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.

## How it works

The GCP join method is available to any Teleport process running on a GCP VM. The VM must have a [service account](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) assigned to it (the default service account is fine). No IAM roles are required on the Teleport process joining the cluster.

Under the hood, services 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.

## 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
     ```

* A GCP VM to host a Teleport service, with a service account assigned to it and with the Teleport binary installed.

* One of the following client tools for managing Teleport resources:

  - The `tctl` CLI, which you can install along with Teleport on your workstation ([documentation](https://goteleport.com/docs/installation.md)) on your workstation.
  - [Teleport Terraform provider](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider.md)
  - [Teleport Kubernetes operator](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider.md)

## Step 1/4. 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. You can create the token with `tctl` as well as the Teleport Terraform provider or Kubernetes operator:

**tctl**

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: ["example@example.com"]

```

Run the following command to create the token:

```
$ tctl create token.yaml
```

**Terraform**

Add the following resource to your Terraform configuration, replacing values as indicated:

```
resource "teleport_provision_token" "gcp-token" {
  version = "v2"
  metadata = {
    name = "gcp-token"
  }

  labels = {
    // This label is added on the Teleport side by default
    "teleport.dev/origin" = "dynamic" 
  }

  spec = {
    // use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop)
    roles       = ["Node"]
    join_method = "gcp"
    gcp = {
      allow = [
        {
          project_ids      = ["example-project-id"]
          locations        = ["us-west1", "us-west2-a"]
          service_accounts = ["example@example.com"]
        },
      ]
    }
  }
}

```

**Kubernetes**

Add the following Kubernetes resource manifest, replacing values as indicated:

```
apiVersion: "resources.teleport.dev/v2"
kind: TeleportProvisionToken
metadata:
  name: "gcp-token"
  labels:
    # This label is added on the Teleport side by default
    "teleport.dev/origin": "dynamic"
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: ["example@example.com"]

```

## Step 2/4 Install Teleport

Install Teleport on your GCP Linux VM.

To install a Teleport Agent on your Linux server:

The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

1. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https\://).

2. Run your cluster's install script:

   ```
   $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
   ```

## Step 3/4. 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: true
auth_service:
  enabled: false
proxy_service:
  enabled: false

```

## Step 4/4. 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.

**Package Manager**

On the host where you will run your Teleport instance, enable and start Teleport:

```
$ sudo systemctl enable teleport
$ sudo systemctl start teleport
```

**TAR Archive**

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.service
$ sudo systemctl enable teleport
$ sudo 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.