Teleport Agents
Teleport agents are Teleport instances that are configured to proxy traffic to resources in your infrastructure, such as servers, databases, and Kubernetes clusters.
This section shows you how to use Teleport agents to enable secure access to your infrastructure.
Architecture overview
Services
Each Teleport process can run one or more services. A Teleport instance runs a service if it is enabled within the instance's configuration file. See the Teleport Configuration Reference for which services are enabled by default and how to enable a particular service.
Agent pools
Agents typically run in the same private networks as the resources they proxy. They should be the only clients that can access a resource without Teleport.
In this setup, agents dial the Teleport Proxy Service in order to establish reverse SSH tunnels. While the Proxy Service remains open to the public internet via its HTTPS port, agents require no open ports or public address.
The Teleport Proxy Service uses these reverse tunnels to forward traffic in Teleport's supported protocols to an available agent. Agents apply RBAC rules and forward the traffic to resources in your infrastructure.
Read our guide for how to use Terraform to deploy a pool of agents.
Joining agents
Initially joining a cluster
Teleport agents need to establish trust with the Teleport Auth Service in order to join a cluster. There are several ways to join an agent to your Teleport cluster, making it possible to automate the join process for your environment. Read about the available join methods in our Join Services to your Cluster guides.
When a Teleport process first runs, it checks its configuration file to determine which services are enabled. Each service then connects separately to the Teleport Auth Service, which checks whether it has created a join token for that service. If so, the Auth Service issues the agent credentials signed for that service.
Joining a new service on an existing agent
The credentials that the Auth Service issues to agents are signed for specific services. To run new services on an agent, you must repeat the initial join procedure for those services.
Generate a new join token for all services running on an agent, including the
new services. Then make the new join token available to the agent. The method to
use depends on the value of either teleport.join_params or
teleport.auth_token in the agent's configuration file:
- If the value of the configuration field is a token, update the token.
- If the value is a file path, edit the file at that path to refer to the new token.
Delete the agent's state directory, which is /var/lib/teleport by default.
(Check the teleport.data_dir field of the agent's configuration file.) With no
data directory, the agent will obtain its initial credentials from the Auth
Service instead of reading existing credentials.
Finally, restart the agent.
We recommend deploying Teleport agents via infrastructure-as-code approaches, e.g., using a Terraform module. To modify the services that an agent runs, you can edit the configuration of your agents within your infrastructure-as-code project, then redeploy the agents.
Enrolling infrastructure
There are two ways to enroll infrastructure resources with Teleport agents:
- Static: Edit an agent's configuration file to configure a specific infrastructure resource to proxy.
- Dynamic: Apply a configuration resource that configures a resource to proxy.
The dynamic method allows Teleport to discover resources automatically. The Discovery Service polls your cloud provider APIs and modifies dynamic infrastructure resources as required.
Read our guide to deploying a pool of agents via Terraform and enrolling infrastructure resources dynamically.
To learn how to enroll resources via static configuration files, plus all the ways Teleport supports enrolling infrastructure, consult our guides to each of Teleport's services: