Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gravitational/teleport/llms.txt

Use this file to discover all available pages before exploring further.

Teleport is a distributed system built around three architectural tiers: the Auth Service, the Proxy Service, and Teleport Agents (services). Understanding how these components interact gives you the foundation needed to deploy, operate, and troubleshoot any Teleport cluster—whether it runs on a single Linux host or spans multiple clouds.

​
The Three Tiers

 ┌──────────────────────────────────────────────────────────────────┐
 │                        CONTROL PLANE                             │
 │                                                                  │
 │  ┌─────────────────────┐      ┌──────────────────────────────┐  │
 │  │   Teleport Auth      │◄────►│   Teleport Proxy Service     │  │
 │  │   Service (CA+DB)    │      │   (Public-facing HTTPS/SSH)  │  │
 │  └─────────────────────┘      └──────────────────────────────┘  │
 │          ▲                               ▲                       │
 └──────────┼───────────────────────────────┼───────────────────────┘
            │ gRPC (mTLS)                   │ Reverse tunnel (SSH)
            │                               │
 ┌──────────┼───────────────────────────────┼───────────────────────┐
 │          │        PRIVATE NETWORK        │                       │
 │  ┌───────┴───────────────────────────────┴──────────────┐        │
 │  │         Teleport Agents  (SSH / Kube / DB / App)      │        │
 │  └───────────────────────────────────────────────────────┘        │
 │                  Your Infrastructure                              │
 └──────────────────────────────────────────────────────────────────┘

​
Teleport Auth Service

The Auth Service is the core of a Teleport cluster. It performs three main functions:
  1. Maintains certificate authorities (CAs). The Auth Service is the root of trust for every component in the cluster. It signs short-lived X.509 and SSH certificates for users, hosts, and internal services. All authentication is certificate-based—there are no shared secrets or static passwords traveling over the wire.
  2. Stores cluster configuration. Dynamic resources such as roles, local users, trusted clusters, and registered infrastructure resources are persisted in the Auth Service’s backend store.
  3. Collects audit events and session recordings. Every connection, command, and access request generates an audit event that is written to the Auth Service’s audit backend.
Teleport services communicate with the Auth Service through a gRPC API secured by mutual TLS.

​
Teleport Proxy Service

The Proxy Service is the public-facing entry point for a Teleport cluster. Users connect to the Proxy Service to reach resources that live in private networks—no VPN required. Key responsibilities include:
  • Routing user traffic. The Proxy Service inspects the protocol (SSH, Kubernetes API, HTTPS, database wire protocol) and forwards the connection to the appropriate agent through a reverse tunnel.
  • Serving the Web UI. The Proxy hosts Teleport’s browser-based interface for managing sessions, access requests, and audit logs.
  • TLS Routing. By default, all traffic (SSH, Kubernetes, databases, applications) is multiplexed over a single TLS port (443), minimizing the number of firewall rules you need.
The Proxy Service is stateless. You can run multiple Proxy instances behind a load balancer for high availability and geographic distribution without any special coordination.

​
Teleport Agents

Teleport Agents are instances of the teleport binary configured to run one or more services that proxy access to your infrastructure. Agents live in your private network alongside the resources they protect.
ServiceProtocolResources
ssh_serviceSSHLinux servers, OpenSSH nodes
kubernetes_serviceHTTPSKubernetes clusters
db_serviceNative DB protocolsPostgreSQL, MySQL, MongoDB, and more
app_serviceHTTPS / TCPInternal web apps, AWS Console
windows_desktop_serviceRDPWindows desktops
discovery_serviceCloud APIsAuto-enrolled EC2, GKE, RDS, etc.
Agents do not need inbound ports open on your firewall. They initiate outbound reverse tunnel connections to the Proxy Service’s SSH server over port 443, and the Proxy forwards user traffic back through those tunnels. This design keeps your infrastructure nodes entirely private.

​
Certificate Flow

Every Teleport connection is secured by short-lived certificates. Understanding the certificate lifecycle is essential for debugging access issues and planning your security posture.
1

User authenticates

A user runs tsh login (or opens the Web UI) and presents their credentials—a password plus MFA, or an SSO assertion from your identity provider. The Proxy Service routes this to the Auth Service.
2

Auth Service issues certificates

The Auth Service verifies the identity, looks up the user’s roles, and issues:
  • An SSH certificate (for SSH and Kubernetes access)
  • An X.509 TLS certificate (for databases, applications, and internal gRPC connections)
Both certificates encode the user’s identity, roles, and an expiry (typically 8–12 hours for humans, minutes for workloads).
3

User presents certificates to agents

When the user runs tsh ssh, tsh kube login, or tsh db connect, the client presents the certificate to the agent. The agent validates it against the cluster’s CA—it does not need to contact the Auth Service for every connection.
4

Agent enforces RBAC

The agent decodes the user’s roles from the certificate and checks the role’s allow/deny rules and label selectors. If the role permits access, the connection is established; otherwise it is rejected and an audit event is emitted.
Because certificates are short-lived, there is no need to maintain revocation lists for the normal case. For immediate lockout (e.g., during a security incident), Teleport supports session and identity locking, which instructs all agents to refuse connections for a specific user or certificate.

​
Internal Certificates

Internal Teleport components—the Auth Service, Proxy Service, and Agents—also use certificates to authenticate to each other. These are longer-lived than user certificates and are renewed during CA rotation, a cluster-wide process that replaces all certificate authorities and reissues all internal certificates.

​
Reverse Tunnels

One of Teleport’s most important deployment advantages is that agents require no inbound network access. When an agent starts, it:
  1. Obtains a join token (a short-lived one-time secret or a cloud identity join method).
  2. Connects outbound to the Proxy Service’s SSH reverse tunnel listener on port 443.
  3. Maintains a persistent, authenticated tunnel.
When a user wants to reach a resource (e.g., an SSH node or a Kubernetes cluster behind a firewall), the Proxy Service routes the connection through the existing reverse tunnel to the agent. The agent sees an inbound session request from an authenticated user and applies RBAC. This means you can enroll servers, databases, and Kubernetes clusters in air-gapped networks, cloud VPCs, or customer environments without changing their inbound firewall rules.

​
Backend Storage

The Auth Service needs a persistent backend for cluster state and audit data. Teleport supports multiple backends, chosen at deploy time via teleport.yaml.
Cluster state includes roles, users, trusted cluster records, node registrations, and certificate authority keys.
BackendEnvironmentNotes
SQLiteDev / single-nodeDefault for new self-hosted installs; not suitable for HA
etcdKubernetes / bare metalSuitable for HA; requires a separate etcd cluster
DynamoDBAWSFully managed; used by Teleport Enterprise Cloud
FirestoreGCPFully managed; used by Teleport on GKE
PostgreSQLAnySupported in Teleport Enterprise; supports HA
Configure the state backend in the storage section of teleport.yaml:
teleport:
  storage:
    type: dynamodb
    region: us-east-1
    table_name: teleport-cluster-state
Session recordings (SSH PTY output, Kubernetes exec output, desktop video) are stored separately from cluster state. Teleport supports:
BackendEnvironmentNotes
FilesystemDev / single-nodeStored at data_dir; not suitable for HA
AWS S3AWSRecommended for production AWS deployments
Google Cloud Storage (GCS)GCPRecommended for production GCP deployments
S3-compatible (MinIO, etc.)AnyConfigurable endpoint
Configure the sessions backend via audit_sessions_uri in teleport.yaml:
teleport:
  storage:
    audit_sessions_uri: s3://my-teleport-recordings?region=us-east-1

​
Teleport Enterprise Cloud

On Teleport Enterprise Cloud, Teleport fully manages the Auth Service and Proxy Service for you. The Auth Service runs in two AWS availability zones for redundancy and the Proxy Service is deployed to multiple regions globally for low-latency access. You deploy only Agents on your own infrastructure. Audit logs are stored in S3 and retained for four years by default; session recordings are retained in S3 indefinitely. Customers can also configure External Audit Storage to route recordings and logs to their own AWS account.

Deploy a Cluster

Step-by-step instructions for deploying Teleport on Linux or Kubernetes.

Configuration Reference

Full annotated teleport.yaml reference for every service section.

Access Controls / RBAC

How roles, labels, and allow/deny rules control access to resources.

Core Concepts

High-level overview of clusters, services, users, and clients.

Build docs developers (and LLMs) love

Get started for freeTalk to us