teleport/docs/pages/installation/agents/add-service-to-agent.mdx

---
title: Enable a New Service on an Agent
sidebar_label: Enabling a New Service
description: Explains how to edit the services that are running on a Teleport Agent.
sidebar_position: 9
tags:
 - how-to
 - zero-trust
 - infrastructure-identity
---

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, update the
agent's join token to one that authorizes the new services, enable the new
services in the agent's configuration file, then restart the agent. The agent
will detect the additional services authorized by the new token and obtain a new
certificate for them.

## Prerequisites

- A Teleport cluster
- At least one Teleport Agent running in your cluster, either on a Linux server
  or a Kubernetes pod
- (!docs/pages/includes/iac-clients.mdx!)
- Familiarity with at least one Teleport join method. Read the [Using Teleport
  Agents overview](agents.mdx) 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:

(!docs/pages/includes/token-types.mdx!)

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:

<Tabs>
<TabItem label="tctl">

Edit the `spec.roles` field in your token resource manifest. In this example,
which assumes the token manifest is at `token.yaml`, we are allowing this token
to join the Teleport Application Service in addition to the Teleport Kubernetes
Service:

```diff
# ...
  spec:
    # use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop)
-   roles: [Kube]
+   roles: [Kube,App]
```

Apply your changes:

```code
$ tctl create -f token.yaml
```

</TabItem>
<TabItem label="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:

```diff
  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"]
```

Reapply your changes:

```code
$ terraform apply
```

</TabItem>
<TabItem label="Kubernetes">

Edit the `spec.roles` field in your manifest, which we assume exists at
`token.yaml`. In this example, we are allowing this token to join the Teleport
Application Service in addition to the Teleport Kubernetes Service:

```diff
# ...
  spec:
    # use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop)
-   roles: [Kube]
+   roles: [Kube,App]
```

Apply your changes:

```code
$ kubectl apply -f token.yaml
```

</TabItem>
<TabItem label="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:

```diff
- roles: kube,
+ roles: kube,app
```

You will apply your changes when you redeploy the agent later in the guide.

See the `teleport-kube-agent` [chart
reference](../../reference/helm-reference/teleport-kube-agent.mdx#roles) for the
roles and token types that the chart supports.

</TabItem>
</Tabs>

## 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:

<Tabs>
<TabItem label="Application Service">

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

```yaml
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`:

```yaml
apps:
  - name: myapp
    # ...
```

</TabItem>
<TabItem label="Database Service">

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

```yaml
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`:

```yaml
databases:
  - name: mydb
    # ...
```

</TabItem>
<TabItem label="Kubernetes Service">

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

```yaml
kubernetes_service:
  enabled: true
```

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

```yaml
kubeClusterName: mycluster
```

</TabItem>
<TabItem label="SSH Service">

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

```yaml
ssh_service:
  enabled: true
```

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

</TabItem>
<TabItem label="Windows Desktop Service">

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

```yaml
windows_desktop_service:
  enabled: true
```

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

</TabItem>
</Tabs>

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](../../enroll-resources/enroll-resources.mdx) 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:

   ```code
   $ tctl tokens ls
   # Token                            Type        Labels Expiry Time (UTC)
   # -------------------------------- ----------- ------ -------------------------------
   # (=presets.tokens.first=) Node,Db,App        10 Aug 23 19:49 UTC (4m11s)
   ```

   In this case, the name of the token is `(=presets.tokens.first=)`.

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

   ```diff
     teleport:
       join_params:
   -     token_name: (=presets.tokens.second=)
   +     token_name: (=presets.tokens.first=)
         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:

   ```code
   $ echo (=presets.tokens.first=) > /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, restart the agent:

```code
$ sudo systemctl restart teleport
```

On the first restart with the new token, the agent will detect the additional
authorized services and retrieve a new certificate for them.

Run the following command to determine if you added the new service,
substituting <Var name="hostname" /> with the hostname of your agent:

```code
$ tctl inventory ls --format=json | \
  jq '.[] | select(.spec.hostname == "<Var name="hostname" />") | .spec.services'
[
  "Node",
  "Db",
  "App"
]
```

The output should include the role of the new service.

<details>
<summary>If the new service has not started</summary>

If the agent fails to acquire the new role after restarting, you can force it
to re-join from scratch by deleting its state directory.

1. Check the `teleport.data_dir` field in the agent's configuration file for the
   location of the data directory. The default is `/var/lib/teleport`.

1. Stop the agent, delete the data directory at 
   <Var name="/var/lib/teleport" />, and start the agent again:

   ```code
   $ sudo systemctl stop teleport
   $ sudo rm -rf <Var name="/var/lib/teleport" />
   $ sudo systemctl start teleport
   ```

</details>

### Helm chart

Upgrade your Helm release:

```code
$ 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](../../reference/infrastructure-as-code/terraform-provider/resources/provision_token.mdx)
- [Kubernetes
  operator](../../reference/infrastructure-as-code/operator-resources/resources-teleport-dev-provisiontokens.mdx)

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](../../configuration/terraform-provider/terraform-getting-started.mdx):
  Using Terraform to launch Teleport Agent instances that depend on join token
  resources.
- [Automatically Register Resources with
  Teleport](../../zero-trust-access/api/automatically-register-agents.mdx): Writing a
  compute platform client that automatically creates join tokens and launches
  Teleport Agents with them.