Enable a New Service on an Agent

Report an issue with this page

A single Teleport Agent can run multiple services. This guide shows you how to adjust the services that a Teleport Agent runs so you can proxy different resources in your infrastructure.

How it works

When a Teleport Agent joins a cluster, it presents a join token to the Teleport Auth Service in order to authenticate itself. A join token is a dynamic resource stored on the Teleport Auth Service backend. It contains a time to live (TTL), name, and a list of Teleport services that the token authorizes to run on the agent.

When a Teleport Agent joins a cluster, the Teleport Auth Service issues a certificate for the agent. The certificate contains the Teleport services that it authorizes the agent to run. To run new services on an agent, you must repeat the initial join procedure for those services. The agent needs to re-join the cluster with the new token and receive a new certificate.

Prerequisites

• A Teleport cluster
• At least one Teleport Agent running in your cluster, either on a Linux server or a Kubernetes pod
• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email@example.com to your Teleport username:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  17.0.0-dev
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

As an example, this guide shows you how to add a service to an agent using the token join method. This is one of multiple available join methods. Read the Using Teleport Agents overview for a complete list.

Step 1/3. Generate a new join token

Generate a new join token for all services running on an agent, including any new services you want to run.

For example, if an agent runs the Teleport Kubernetes Service, and you want it to run the Teleport Application Service as well, create a join token for the Teleport Kubernetes Service and Teleport Application Service. To do so, specify the two services in the --type flag of tctl tokens add:

tctl tokens add --type=kube,app --ttl=5m

You can specify the following token types:

Role	Teleport Service
app	Application Service
auth	Auth Service
bot	Machine ID
db	Database Service
discovery	Discovery Service
kube	Kubernetes Service
node	SSH Service
proxy	Proxy Service
windowsdesktop	Windows Desktop Service

If you are running your Teleport Agent using the teleport-kube-agent Helm chart, once you know your token types, update your values file so the roles field includes your required roles.

For example, this change adds the app role to enable the Teleport Application Service:

- roles: kube,db
+ roles: kube,app,db

See the teleport-kube-agent chart reference for the roles and token types that the chart supports.

Step 2/3. Edit your agent configuration

All Teleport Agent services run concurrently on the same teleport process. When the teleport daemon starts, it loads its configuration file (/etc/teleport.yaml by default) and determines which services to run. The configuration file also contains a reference to the join token the agent presents to the Teleport Auth Service in order to authenticate.

Enable the new service

In the Teleport configuration file, top-level configuration fields that include the substring _service indicate whether to run a given Teleport service.

To enable a service, add the configuration field for your service with the enabled field set to true. The following configuration snippets are examples of enabling each Teleport Agent service in the configuration file:

Application Service

If the Teleport Agent runs on a Linux server, edit the configuration file to enable the new service:

app_service:
  enabled: true

If the Teleport Agent runs using the teleport-kube-agent chart, edit the values file to add an entry to apps:

apps:
  - name: myapp
    # ...

Database Service

If the Teleport Agent runs on a Linux server, edit the configuration file to enable the new service:

db_service:
  enabled: true

If the Teleport Agent runs using the teleport-kube-agent chart, edit the values file to add an entry to databases:

databases:
  - name: mydb
    # ...

Kubernetes Service

If the Teleport Agent runs on a Linux server, edit the configuration file to enable the new service:

kubernetes_service:
  enabled: true

If the Teleport Agent runs using the teleport-kube-agent chart, edit the values file to add the kubeClusterName field:

kubeClusterName: mycluster

SSH Service

If the Teleport Agent runs on a Linux server, edit the configuration file to enable the new service:

ssh_service:
  enabled: true

The Teleport SSH Service is not available for the teleport-kube-agent chart.

Windows Desktop Service

If the Teleport Agent runs on a Linux server, edit the configuration file to enable the new service:

windows_desktop_service:
  enabled: true

The Windows Desktop Service is not available for the teleport-kube-agent chart.

Note that while the examples above enable a new service, they do not configure it to proxy any resources. Read a guide to enrolling resources for how to configure the new Teleport service.

Update the join token

Make sure the agent's configuration file refers to the new join token.

1. Find the name of the join token you created:

   tctl tokens ls
   Token                            Type        Labels Expiry Time (UTC)
   -------------------------------- ----------- ------ -------------------------------
   abcd123-insecure-do-not-use-this Node,Db,App        10 Aug 23 19:49 UTC (4m11s)

   In this case, the name of the token is abcd123-insecure-do-not-use-this.

2. In the agent's configuration file, update teleport.join_params or teleport.auth_token:

     teleport:
       join_params:
   -     token_name: efgh456-insecure-do-not-use-this
   +     token_name: abcd123-insecure-do-not-use-this
         method: token
   

   If the value of this field is a file path, edit the file at that path to refer to the name of the new token. For example, if the value of the field is /var/lib/teleport/token, run the following command:

   echo abcd123-insecure-do-not-use-this > /var/lib/teleport/token

   If you are using the teleport-kube-agent Helm chart to deploy an Agent, check your values file for either the authToken field or the joinParams.tokenName field instead.

Step 3/3. Start Teleport Agents with the new join tokens

Restart your Teleport Agent so it rejoins the cluster with the new token and receives a certificate that authorizes the additional service you want to run.

Linux server

If your Teleport Agent runs on a Linux server:

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

2. Restart the agent:

   sudo systemctl reload teleport

Helm chart

Upgrade your Helm release:

helm upgrade teleport-agent teleport-kube-agent

Further reading: manage tokens as code

While this guide shows you how to create a token using tctl, you can also manage tokens using the Teleport Terraform provider or Kubernetes operator. See the following documentation for information on the token resource:

• Terraform provider
• Kubernetes operator

You can set up a system to automate the process of assigning join tokens to agents, ensuring that all Teleport services you run have the correct join token permissions. Here are examples in the documentation:

• Enroll Infrastructure with Terraform: Using Terraform to launch Teleport Agent instances that depend on join token resources.
• Automatically Register Resources with Teleport: Writing a compute platform client that automatically creates join tokens and launches Teleport Agents with them.