Skip to main content

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.

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.

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

To discover your current GCP project ID, run:

gcloud config get-value project

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.

Run on your workstation:

gcloud compute instance-templates create teleport-auth-template \    --machine-type=n1-standard-2 \    --image-family=ubuntu-2204-lts \    --image-project=ubuntu-os-cloud \    --boot-disk-size=20GB \    --service-account=$SERVICE_ACCOUNT \    --scopes=cloud-platform \    --tags=teleport-auth

gcloud compute instance-groups managed create teleport-auth-group \    --template=teleport-auth-template \    --size=2 \    --zone=us-central1-a

gcloud compute instance-templates create teleport-proxy-template \    --machine-type=n1-standard-2 \    --image-family=ubuntu-2204-lts \    --image-project=ubuntu-os-cloud \    --boot-disk-size=20GB \    --service-account=$SERVICE_ACCOUNT \    --scopes=cloud-platform \    --tags=teleport-proxy

gcloud compute instance-groups managed create teleport-proxy-group \    --template=teleport-proxy-template \    --size=2 \    --zone=us-central1-a

Compute Engine: Health Checks​

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

To enable health checks in Teleport start with teleport start --diag-addr=0.0.0.0:3000 see Admin Guide: Troubleshooting for more information.

Run on your workstation:

gcloud compute health-checks create http teleport-auth-healthcheck \    --port=3000 \    --request-path=/healthz \    --check-interval=10s \    --timeout=5s \    --unhealthy-threshold=3 \    --healthy-threshold=2

gcloud compute health-checks create http teleport-proxy-healthcheck \    --port=3000 \    --request-path=/healthz \    --check-interval=10s \    --timeout=5s \    --unhealthy-threshold=3 \    --healthy-threshold=2
note

Create a separate health check for each instance group. Auth and Proxy Service instances run on different hosts, so pointing a Proxy backend at the Auth health check (or vice versa) will cause health checks to fail even when the service is healthy.

Checkpoint:

Verify the health checks were created:

gcloud compute health-checks list --format="value(name, type)"

You should see both teleport-auth-healthcheck and teleport-proxy-healthcheck listed.

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

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.

Run on your workstation to create a Firestore database in native mode:

gcloud firestore databases create \    --location=us-central1 \    --type=firestore-native \    --project=Example_GCP_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):

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' ]
Table Names

Be careful to ensure that Example_FIRESTORE_CLUSTER_STATE and Example_FIRESTORE_AUDIT_LOGS refer to different Firestore collections. The schema is different for each, and using the same collection for both types of data will result in errors.

Checkpoint:

Verify Firestore is available:

gcloud firestore databases describe --project=Example_GCP_PROJECT --format="value(name, type)"

You should see a database name and the type FIRESTORE_NATIVE.

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

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.

Run on your workstation to create the bucket:

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

When creating the Bucket, we recommend setting it up as Dual-region with the Standard storage class. Provide access using a Uniform access control with a Google-managed key.

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'
    ...

Checkpoint:

Verify the bucket was created:

gcloud storage buckets describe gs://Example_BUCKET_NAME --format="value(name, location)"

You should see your bucket name and its location.

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

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.

Use passthrough Network Load Balancing, not TCP Proxy Load Balancing

GCP's Target TCP Proxy load balancer (gcloud compute target-tcp-proxies) only forwards traffic on a small fixed set of ports (25, 43, 110, 143, 195, 443, 465, 587, 700, 993, 995, 1883, and 5222) — it does not support Teleport's ports (443, 3023-3026, 3036). Use a regional external passthrough Network Load Balancer instead, which supports any combination of ports.

Run on your workstation:

gcloud compute target-pools create teleport-proxy-pool \    --region=us-central1 \    --health-check=teleport-proxy-healthcheck

gcloud compute target-pools add-instances teleport-proxy-pool \    --instances-zone=us-central1-a \    --instance-group=teleport-proxy-group

gcloud compute addresses create teleport-lb-ip \    --region=us-central1

export LB_IP=$(gcloud compute addresses describe teleport-lb-ip --region=us-central1 --format="value(address)")

gcloud compute forwarding-rules create teleport-forwarding-rule \    --region=us-central1 \    --address=$LB_IP \    --ip-protocol=TCP \    --ports=443,3023,3024,3025,3026,3036 \    --target-pool=teleport-proxy-pool
note

Reserving a static external IP address (teleport-lb-ip above) before creating the forwarding rule means your Teleport Proxy's public address won't change if you ever need to recreate the forwarding rule. If you're fine with an ephemeral address instead, you can omit the addresses create step and the --address flag.

Checkpoint:

Verify the load balancer was created and its target pool has healthy members:

gcloud compute forwarding-rules describe teleport-forwarding-rule --region=us-central1 --format="value(IPAddress)"
gcloud compute target-pools get-health teleport-proxy-pool --region=us-central1

The first command should return the same IP as $LB_IP. The second should show HEALTHY for each Proxy instance — if an instance shows UNHEALTHY, confirm Teleport is running with --diag-addr=0.0.0.0:3000 on that host.

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

Network Services: Cloud DNS​

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

Run on your workstation:

Create a DNS managed zone (if you don't already have one)
gcloud dns managed-zones create teleport-zone \    --dns-name="example.com." \    --description="DNS zone for Teleport"

Re-fetch the reserved load balancer IP if you're in a new shell session
export LB_IP=$(gcloud compute addresses describe teleport-lb-ip --region=us-central1 --format="value(address)")

Create an A record pointing to the load balancer
gcloud dns record-sets create teleport.example.com. \    --zone=teleport-zone \    --type=A \    --ttl=300 \    --rrdatas=$LB_IP

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.

If you want Teleport to be able to create its own GCS bucket, you'll need to create a role allowing the storage.buckets.create permission. You can skip this step if you choose to 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:
# Allow Teleport to create the GCS bucket for session
# recordings if it doesn't already exist.
- storage.buckets.create

Run on your workstation:

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

Checkpoint:

Verify the service account has the correct roles:

gcloud projects get-iam-policy Example_GCP_PROJECT \    --flatten="bindings[].members" \    --filter="bindings.members:serviceAccount:$SERVICE_ACCOUNT" \    --format="table(bindings.role)"

You should see the custom IAM role, roles/datastore.owner, and roles/storage.objectAdmin listed.

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

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.

GCP Quickstart​

1. 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.

Checkpoint:

Verify all required GCP resources are ready before proceeding:

Verify Firestore database exists
gcloud firestore databases describe --project=Example_GCP_PROJECT --format="value(type)"

Verify GCS bucket exists
gcloud storage buckets describe gs://Example_BUCKET_NAME --format="value(name)"

Verify service account exists
gcloud iam service-accounts describe $SERVICE_ACCOUNT --format="value(email)"

All three commands should return valid output without errors.

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

2. Install & Configure Teleport​

Follow install instructions from our installation page.

We recommend configuring Teleport as per the below steps:

1. Configure Teleport Auth Service using 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
#
teleport:
  nodename: teleport-auth-server
  data_dir: /var/lib/teleport
  pid_file: /run/teleport.pid
  log:
    output: stderr
    severity: DEBUG
  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
  tokens:
    - "proxy:abcd123-insecure-do-not-use-this"
    - "node:efgh456-insecure-do-not-use-this"
proxy_service:
  enabled: false
ssh_service:
  enabled: false

2. Set up Proxy

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

# enable multiplexing all traffic on TCP port 443
version: v3
teleport:
  auth_token: abcd123-insecure-do-not-use-this
  # We recommend using a TCP load balancer pointed to the auth servers when
  # setting up in High Availability mode.
  auth_server: auth.example.com:3025
# enable proxy service, disable auth and ssh
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
  # automatically get an ACME certificate for teleport.example.com (works for a single proxy)
  acme:
    enabled: true
    email: example@email.com

3. Set up Teleport Nodes

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

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
# enable the SSH Service and disable the Auth and Proxy Services
ssh_service:
  enabled: true
auth_service:
  enabled: false
proxy_service:
  enabled: false

4. Start services and verify

Run on each Teleport host:

sudo systemctl enable teleport
sudo systemctl start teleport
sudo systemctl status teleport

Checkpoint:

Verify the Teleport Auth Service is running and connected to its backend:

sudo journalctl -u teleport --no-pager -n 20 | grep -i "started\|error\|firestore"

You should see log lines indicating the Auth Service has started and connected to Firestore without errors.

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

5. Add Users

Follow our Local Users guide or integrate with Google Workspace to provide SSO access.