Skip to main content
Version: 19.x (unreleased)

Running Teleport on GCP

Report an Issue

We've created this guide to give customers an overview of how to deploy a self-hosted Teleport cluster on Google Cloud (GCP). This guide provides a high-level introduction to setting up and running Teleport in production.

We have split this guide into:

tip

Teleport Enterprise Cloud takes care of this setup for you so you can provide secure access to your infrastructure right away.

Get started with a free trial of Teleport Enterprise Cloud.

Prerequisites​

Before proceeding, ensure the following GCP APIs are enabled on your project. This applies whether you follow the GCP Teleport Introduction below or jump straight to the GCP Quickstart.

  • Cloud Resource Manager API
  • Compute Engine API
  • Cloud Firestore API
  • Cloud DNS API
  • IAM API
  • Cloud Storage API

You can enable them with:

gcloud services enable \    cloudresourcemanager.googleapis.com \    compute.googleapis.com \    firestore.googleapis.com \    dns.googleapis.com \    iam.googleapis.com \    storage.googleapis.com \    --project Example_GCP_PROJECT

Throughout this guide, we'll make use of the following placeholder variables. Please replace them with values appropriate for your environment.

NameExampleDescription
Example_GCP_PROJECTteleport-projectYour GCP project ID
Example_GCP_CREDENTIALS/var/lib/teleport/google.jsonPath to service account credentials
Example_FIRESTORE_CLUSTER_STATEteleport-cluster-stateName of the Firestore collection for Teleport cluster state
Example_FIRESTORE_AUDIT_LOGSteleport-audit-logsName of the Firestore collection for Teleport audit logs
Example_BUCKET_NAMEteleport-session-recordingsName of the GCS bucket for session recording storage

GCP Teleport Introduction​

This guide will cover how to set up, configure and run Teleport on GCP.

The following GCP Services are required to run Teleport in high availability mode:

Other things needed:

Optional:

  • Management Tools: Cloud Deployment Manager
  • Logging: Stackdriver

We recommend setting up Teleport in high availability mode. In high availability mode Firestore is used for cluster state and audit logs, and Google Cloud Storage is used for session recordings.

Compute Engine: VM Instances with Instance Groups​

We recommend using n1-standard-2 instances in production. It's best to separate Teleport Proxy Service and Auth Service instances using instance groups for each.

Compute Engine: Health Checks​

GCP relies heavily on Health Checks, this is helpful when adding new instances to an instance group.

Each Teleport service instance: the Proxy Service, the Auth Service, or a host running the SSH Service, has its own teleport.yaml. To enable health checks for an instance, set diag_addr in that instance's config file. Only the Proxy Service should bind to all interfaces (0.0.0.0) since it needs to respond to GCP load balancer health checks. Instances running the Auth Service or SSH Service should bind to loopback (127.0.0.1) to avoid exposing unauthenticated diagnostic endpoints (including /metrics) to the network:

# Proxy Service — exposed to GCP health checks
teleport:
  diag_addr: 0.0.0.0:3000

# Auth Service and SSH Service — loopback only
teleport:
  diag_addr: 127.0.0.1:3000

Configure your GCP health check as an HTTP health check against the /readyz path on port 3000. The /readyz endpoint returns HTTP 200 only when the service is fully ready to handle traffic, unlike /healthz which reports liveness regardless of whether the service has finished initializing.

Restrict the firewall rule for port 3000 to GCP health check source ranges (35.191.0.0/16 and 130.211.0.0/22).

Storage: Cloud Firestore​

The Firestore backend uses real-time updates to keep individual Auth Service instances in sync, and requires Firestore configured in native mode.

Teleport requires the default Firestore database (database ID (default)) in Native mode. If your project does not have a default Firestore database, create one:

gcloud firestore databases create \    --database='(default)' \    --location=Example_FIRESTORE_LOCATION \    --type=firestore-native \    --project=Example_GCP_PROJECT

Replace Example_FIRESTORE_LOCATION with a supported Firestore location close to your Compute Engine instances (e.g., us-central1, europe-west1). This is a one-time, irreversible setting per project. If your project already has Firestore in Datastore mode, you will need to use a different project.

To configure Teleport to store audit events in Firestore, add the following to the teleport section of your Auth Service's config file (by default it's /etc/teleport.yaml). Make sure Example_FIRESTORE_CLUSTER_STATE and Example_FIRESTORE_AUDIT_LOGS refer to different Firestore collections as the schema differs for each, and reusing one collection for both will result in errors:

teleport:
  storage:
    type: firestore
    collection_name: Example_FIRESTORE_CLUSTER_STATE
    project_id: Example_GCP_PROJECT
    credentials_path: Example_GCP_CREDENTIALS
    audit_events_uri: [ 'firestore://Example_FIRESTORE_AUDIT_LOGS?projectID=Example_GCP_PROJECT&credentialsPath=Example_GCP_CREDENTIALS' ]

On first startup, Teleport creates composite indexes in Firestore. This can take 5-10 minutes, during which Teleport logs "Still creating indexes" repeatedly—this is expected, so let it finish rather than restarting the service.

Storage: Google Cloud Storage​

The Google Cloud Storage backend is used for Teleport session recordings. Teleport will try to create the bucket on startup if it doesn't already exist. If you prefer, you can create the bucket ahead of time. In this case, Teleport does not need permissions to create buckets.

When creating the bucket, we recommend setting it up as Dual-region with the Standard storage class, using Uniform access control with a Google-managed key. The --location=us flag below creates a multi-region bucket for high availability; for a dual-region bucket, use --placement=us-central1,us-east1 instead of --location, choosing regions appropriate for your deployment:

gcloud storage buckets create gs://Example_BUCKET_NAME \    --project=Example_GCP_PROJECT \    --location=us \    --default-storage-class=STANDARD \    --uniform-bucket-level-access

When setting up audit_sessions_uri use the gs:// prefix.

storage:
    ...
    audit_sessions_uri: 'gs://Example_BUCKET_NAME?projectID=Example_GCP_PROJECT&credentialsPath=Example_GCP_CREDENTIALS'
    ...

Network Services: Load Balancing​

Load Balancing is required for Proxy and SSH traffic. Use TCP Load Balancing as Teleport requires custom ports for SSH and Web Traffic.

Network Services: Cloud DNS​

Cloud DNS is used to set up the public URL of the Teleport Proxy.

Access: Service accounts​

The Teleport Auth Service will need to read and write to Firestore and Google Cloud Storage. For this you will need a Service Account with the correct permissions.

Teleport requires storage.buckets.get to verify the GCS bucket on startup. If you also want Teleport to create the bucket automatically, add storage.buckets.create. You can omit storage.buckets.create if you pre-create the bucket before installing Teleport.

To create this role, start by defining the role in a YAML file:

# teleport_auth_role.yaml
title: teleport_auth_role
description: 'Teleport permissions for GCP'
stage: ALPHA
includedPermissions:
# Required: Teleport verifies the bucket exists on startup.
- storage.buckets.get
# Optional: only needed if Teleport should create the bucket itself.
# Remove this permission if you pre-create the bucket.
- storage.buckets.create

Create the role using this file:

gcloud iam roles create teleport_auth_role \    --project Example_GCP_PROJECT \    --file teleport_auth_role.yaml \    --format yaml

Note the name field in the output which is the fully qualified name for the custom role and must be used in later steps.

export IAM_ROLE=<role name output from above>

If you don't already have a GCP service account for your Teleport Auth Service you can create one with the following command, otherwise use your existing service account.

gcloud iam service-accounts create teleport-auth-server \    --description="Service account for Teleport Auth Service" \    --display-name="Teleport Auth Service" \    --format=yaml

Note the email field in the output, this must be used as the identifier for the service account.

export SERVICE_ACCOUNT=<email output from above command>

Lastly, bind the required IAM roles to your newly created service account.

our custom IAM role allows Teleport to create the GCS
bucket for session recordings if it doesn't already exist
gcloud projects add-iam-policy-binding Example_GCP_PROJECT \    --member=serviceAccount:$SERVICE_ACCOUNT \    --role=$IAM_ROLE

datastore.owner grants the required Firestore access
gcloud projects add-iam-policy-binding Example_GCP_PROJECT \    --member=serviceAccount:$SERVICE_ACCOUNT \    --role=roles/datastore.owner

storage.objectAdmin is needed to read/write/delete storage objects
gcloud projects add-iam-policy-binding Example_GCP_PROJECT \    --member=serviceAccount:$SERVICE_ACCOUNT \    --role=roles/storage.objectAdmin

Download JSON Service Key

The credentials for this service account should be exported in JSON format and provided to Teleport throughout the remainder of this guide.

gcloud iam service-accounts keys create google.json \    --iam-account=$SERVICE_ACCOUNT

Copy the resulting google.json file to /var/lib/teleport/google.json on your Auth Service instance and set appropriate permissions:

sudo mkdir -p /var/lib/teleport
sudo mv google.json /var/lib/teleport/google.json
sudo chmod 600 /var/lib/teleport/google.json

GCP Quickstart​

Step 1/6. Create resources​

We recommend starting by creating the resources. We highly recommend creating these using an infrastructure automation tool such as Cloud Deployment Manager or Terraform.

Step 2/6. Install and configure Teleport​

Follow install instructions from our installation page.

We recommend configuring Teleport as per the below steps:

Configure the Auth Service​

Use the below example teleport.yaml, and start it using systemd. The DEB/RPM installations will automatically include the systemd configuration.

#
# Sample Teleport configuration teleport.yaml file for Auth Service
#
version: v3
teleport:
  nodename: teleport-auth-server
  data_dir: /var/lib/teleport
  log:
    output: stderr
    severity: DEBUG
  diag_addr: 127.0.0.1:3000
  storage:
    type: firestore
    collection_name: Example_FIRESTORE_CLUSTER_STATE
    # Credentials: Path to google service account file, used for Firestore and Google Storage.
    credentials_path: Example_GCP_CREDENTIALS
    project_id: Example_GCP_PROJECT
    audit_events_uri: 'firestore://Example_FIRESTORE_AUDIT_LOGS?projectID=Example_GCP_PROJECT&credentialsPath=Example_GCP_CREDENTIALS'
    audit_sessions_uri: 'gs://Example_BUCKET_NAME?projectID=Example_GCP_PROJECT&credentialsPath=Example_GCP_CREDENTIALS'
auth_service:
  enabled: true
  listen_addr: 0.0.0.0:3025
  cluster_name: teleport.example.com
  tokens:
    - "proxy:abcd123-insecure-do-not-use-this"
    - "node:efgh456-insecure-do-not-use-this"
proxy_service:
  enabled: false
ssh_service:
  enabled: false

Generate join tokens with:

openssl rand -hex 16

Use one token for the proxy: prefix and a different token for the node: prefix.

Step 3/6. Set up the Proxy Service​

Save the following configuration file as /etc/teleport.yaml on the Proxy Server:

version: v3
teleport:
  auth_token: abcd123-insecure-do-not-use-this
  # Replace with the internal IP or DNS name of your Auth Service instance,
  # or a TCP load balancer pointed to the Auth Service in HA mode.
  auth_server: auth.example.com:3025
  diag_addr: 0.0.0.0:3000
ssh_service:
  enabled: false
auth_service:
  enabled: false
proxy_service:
  enabled: true
  web_listen_addr: 0.0.0.0:443
  public_addr: teleport.example.com:443
  acme:
    enabled: true
    email: [email protected]

The auth_server field must point to the internal IP address or internal DNS name of your Auth Service instance (e.g., 10.128.0.6:3025). In high availability mode, use a TCP internal load balancer in front of your Auth Service instances.

ACME and high availability

Built-in ACME certificate issuance only works with a single Proxy Service instance. In high availability deployments with multiple proxies, concurrent ACME challenges can exhaust failed-authorization rate limits and prevent certificate issuance. For HA, provision a certificate externally (e.g., from your organization's CA or a load balancer) and share it across all Proxy instances.

If you don't have a domain name and are running a single proxy, you can disable the acme section entirely. Teleport will generate self-signed certificates automatically, but clients will need to use --insecure or trust the Teleport CA.

Step 4/6. Set up the SSH Service​

Save the following configuration file as /etc/teleport.yaml on each host that will run the SSH Service:

version: v3
teleport:
  auth_token: efgh456-insecure-do-not-use-this
  # Teleport Agents can be joined to the cluster via the Proxy Service's
  # public address. This will establish a reverse tunnel between the Proxy
  # Service and the agent that is used for all traffic.
  proxy_server: teleport.example.com:443
  diag_addr: 127.0.0.1:3000
ssh_service:
  enabled: true
auth_service:
  enabled: false
proxy_service:
  enabled: false

Step 5/6. Start services​

On each instance, enable and start Teleport via systemd:

sudo systemctl enable teleport
sudo systemctl start teleport

On the Auth Service's first startup, Teleport creates Firestore indexes, which can take 5-10 minutes. Monitor progress with:

sudo journalctl -u teleport -f

Wait until you see the Auth Service listening on port 3025 before starting the Proxy Service or SSH Service instances.

Step 6/6. Add users​

Once all services are running, create a local user on the Auth Service instance:

sudo tctl users add myuser --roles=access,editor --logins=root,ubuntu

This generates an invite URL that can be opened in a browser to complete registration with a password and multi-factor.

Next steps​