# Enable a New Service on an Agent 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 - One of the following client tools for managing Teleport resources: - The `tctl` CLI, which you can install along with Teleport on your workstation ([documentation](https://goteleport.com/docs/installation.md)) on your workstation. - [Teleport Terraform provider](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider.md) - [Teleport Kubernetes operator](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider.md) - Familiarity with at least one Teleport join method. Read the [Using Teleport Agents overview](https://goteleport.com/docs/enroll-resources/agents.md) for a complete list of guides to joining Teleport Agents. This guide assumes that you have followed at least one how-to guide for joining a Teleport Agent. ## 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. You can specify the following token types: | Role | Teleport Service | | ---------------- | ------------------------------- | | `app` | Application Service | | `auth` | Auth Service | | `bot` | Machine & Workload Identity Bot | | `db` | Database Service | | `discovery` | Discovery Service | | `kube` | Kubernetes Service | | `node` | SSH Service | | `proxy` | Proxy Service | | `windowsdesktop` | Windows Desktop Service | 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. Modify the token type in the configuration you used to create the token, depending on your infrastructure as code tool and whether your agent runs from the `teleport-kube-agent` Helm chart: **tctl** Edit the `spec.roles` field in your token resource manifest. In this example, we are allowing this token to join the Teleport Application Service in addition to the Teleport Kubernetes Service: ``` # ... spec: # use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop) - roles: [Kube] + roles: [Kube,App] ``` **Terraform** Edit the `spec.roles` field in your resource configuration. In this example, we are allowing this token to join the Teleport Application Service in addition to the Teleport Kubernetes Service: ``` resource "teleport_provision_token" "current" { // ... spec = { // use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop) - roles = ["Kube"] + roles = ["Kube","App"] ``` **Kubernetes** Edit the `spec.roles` field in your manifest. In this example, we are allowing this token to join the Teleport Application Service in addition to the Teleport Kubernetes Service: ``` # ... spec: # use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop) - roles: [Kube] + roles: [Kube,App] ``` **teleport-kube-agent** Edit the `roles` field in your values file. In this example, we are allowing this token to join the Teleport Application Service in addition to the Teleport Kubernetes Service: ``` - roles: kube, + roles: kube,app ``` See the `teleport-kube-agent` [chart reference](https://goteleport.com/docs/reference/helm-reference/teleport-kube-agent.md#roles) 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](https://goteleport.com/docs/enroll-resources.md) 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](https://goteleport.com/docs/reference/infrastructure-as-code/terraform-provider/resources/provision_token.md) - [Kubernetes operator](https://goteleport.com/docs/reference/infrastructure-as-code/operator-resources/resources-teleport-dev-provisiontokens.md) 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](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider/terraform-getting-started.md): Using Terraform to launch Teleport Agent instances that depend on join token resources. - [Automatically Register Resources with Teleport](https://goteleport.com/docs/zero-trust-access/api/automatically-register-agents.md): Writing a compute platform client that automatically creates join tokens and launches Teleport Agents with them.