Add Labels to Resources - Teleport

Teleport allows you to add arbitrary key-value pairs to applications, servers, databases, and other resources in your cluster. You can use labels to do the following:

Filter the resources returned when running tctl and tsh commands.
Define roles that limit the resources Teleport users can access.

This guide demonstrates how to add labels to enrolled server resources. However, you can follow similar steps to add labels to other types of resources.

How it works

The labels you assign to resources can be static labels, dynamic labels, or resource-based labels.

Static labels are hardcoded in the Teleport configuration file and don't change while the teleport process is running. For example, you might use a static label to identify the resources in a staging or production environment.
Dynamic labels—also known as commands-based labels—allow you to generate labels at runtime. With a dynamic label, the teleport process executes an external command on its host at a configurable frequency and the output of the command becomes the label value.
Resource-based labels allow you to add labels to an instance without restarting the teleport process or editing the configuration file.

You can add multiple static, dynamic, and resource-based labels for the same resource. However, you can't add static labels that use the same key with different values or use a static label to define multiple potential values.

Dynamic labels are especially useful for decoupling a label value from the Teleport configuration. For example, if you start Teleport on an Amazon EC2 instance, you can use a dynamic label to set the region value based on the result from a command sent to the EC2 instance metadata API. The dynamic label enables you to use the same configuration for each server in an Amazon Machine Image but filter and limit access to the servers based on their AWS region.

Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

A Linux host where you will run a Teleport Agent. This guide shows you how to apply labels to an instance of the Teleport SSH Service. You can use the technique shown in the guide to label any Teleport-protected resource.

(!docs/pages/includes/tctl.mdx!)

Step 1/2. Install Teleport

Select a Linux server where you will run a Teleport Agent.
(!docs/pages/includes/install-linux.mdx!)
Generate an invitation token for the host.

The invitation token is required for the local computer to join the Teleport cluster. The following example generates a new token that is valid for five minutes and can be used to enroll a server:
code
```
$ tctl tokens add --ttl=5m --type=node
# The invite token: (=presets.tokens.first=)
```

List all generated non-expired tokens by running the following command:

code

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

Write the join token to a file on the host at /tmp/token:
code
```
$ echo (=presets.tokens.first=) | sudo tee /tmp/token
```
On the host where you plan to run the Agent, generate a configuration file that enables the Teleport SSH Service. Replace teleport.example.com with the host and port of your Teleport Proxy Service or Teleport Enterprise (Cloud) account:
code
```
$ sudo teleport configure \
  --token="/tmp/token" \
  --roles=node \
  --proxy=example.teleport.sh:443 \
  -o file
```

Step 2/2. Apply labels

Follow any or all of the sections below to add different types of labels to your resource.

Apply a static label

You can configure static labels by editing the Teleport configuration file, then starting Teleport.

To add a static label:

Open the Teleport configuration file, /etc/teleport.yaml, in an editor on the computer where you installed the Teleport Agent.
Locate the labels configuration under the ssh_service section.
Add the static label key and value. For example, add environment as the label key and dev as the value:
yaml
```
ssh_service:
  enabled: true
  labels:
    environment: dev
```
The preceding example illustrates a simple value setting. However, you can also use static labels to define more complex string values that include white space or punctuation marks. For example:
code
```
ssh_service:
  enabled: true
  labels:
    location: San Francisco Bldg 301 4th floor
```
Save your changes and close the file.
Start Teleport on the Linux host:

(!docs/pages/includes/start-teleport.mdx!)
Verify that you have added the label by running the following command on your local computer.
code
```
$ tsh ls --query 'labels["environment"]=="dev"'
```
You should see output similar to the following:
code
```
Node Name        Address    Labels
---------------- ---------- ------------------------------------------
ip-192-168-13-57 ⟵ Tunnel   environment=dev,hostname=ip-192-168-13-57
```
Checking the status of your server

If you don't see your server listed when you query for the label you added, you should verify that the SSH Service is running on the server. Check the log for the server to verify that there are messages similar to the following:
text
```
2023-08-07T22:22:21Z INFO [NODE:1]    Service is starting in tunnel mode. pid:149932.1 service/service.go:2630
2023-08-07T22:22:21Z INFO [UPLOAD:1]  starting upload completer service pid:149932.1 service/service.go:2723
2023-08-07T22:22:21Z INFO [PROC:1]    The new service has started successfully. Starting syncing rotation status...
```
Checking your user profile

If the SSH Service is running on the server, verify that your current Teleport user has a login on the local host. You can check the status of your user account by running the following command:
code
```
$ tsh status
```
You should see output similar to the following with at least one login listed for your current user:
code
```
> Profile URL:        https://ajuba-aws.teledocs.click:443
  Logged in as:       teleport-admin
  Cluster:            teleport-aws.example.com
  Roles:              access, editor
  Logins:             root, ubuntu, ec2-user
  Kubernetes:         enabled
  Valid until:        2023-08-08 10:08:46 +0000 UTC [valid for 10h36m0s]
  Extensions:         login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy
```
If no valid logins have been assigned to the user, you should update your current user profile to include at least one valid login.

You can add logins to a user by running a command similar to the following:
code
```
$ tctl users update myuser --set-logins=root
```
This example adds the root login to the myuser Teleport user. For more information about managing logins for Teleport users, see Local Users.

Using hidden static labels

If you want to use labels for role-based access control but don't want to display the labels in command output or the Teleport Web UI, you can define them in a hidden namespace by prefixing the label key with teleport.hidden/. For example:

yaml

ssh_service:
  enabled: true
  labels:
    teleport.hidden/team-id: ai-lab-01

Apply dynamic labels using commands

As with static labels, you can apply dynamic labels by editing the Teleport configuration file, then restarting the Teleport service on your server.

To add a command to generate a dynamic label:

Stop the Teleport service running on your server.
Open the Teleport configuration file—by default, /etc/teleport.yaml—in a text editor.
Locate the commands configuration under the ssh_service section.
Add a command array that runs the uname command with the -p argument to return the architecture of the host server every one hour.

For example, add the name, command, and period fields as follows:
yaml
```
...
ssh_service:
  enabled: true
  labels:
    teleport.internal/resource-id: 1f2cdcc5-cde3-41fa-b390-bc872087821a
    environment: dev
  commands:
  - name: hostname
    command: [hostname]
    period: 1m0s
  - name: arch
    command: [uname, -p]
    period: 1h0m0s
```
In the command setting, the first element is a valid executable. Each subsequent element is an argument. The following syntax is valid:
yaml
```
command: ["/bin/uname", "-m"]
```
The following syntax is not valid:
yaml
```
command: ["/bin/uname -m"]
```
For more complex commands, you can use single (') and double (") quotation marks interchangeably to create nested expressions. For example:
yaml
```
command: ["/bin/sh", "-c", "uname -a | egrep -o '[0-9]+\\.[0-9]+\\.[0-9]+'"]
```
In configuring commands, keep the following in mind:
- The executable must be discoverable in the $PATH or specified using an absolute path.
- You must set the executable permission bit on any file you use as a command.
- Shell scripts must have a shebang line.
The period setting specifies how frequently Teleport executes each command. In this example, the uname -p command is executed every one hour (1h), zero minutes (0m), and zero seconds (0s). This value can't be less than one minute.
Save your changes and close the file.
Start Teleport with the invitation token you saved in the INVITE_TOKEN environment variable:
code
```
$ sudo teleport start --token=${INVITE_TOKEN?}
```
Verify that you have added the label by running the following command on your local computer. Your Teleport user must be authorized to access the server.
code
```
$ tsh ls
```
You should see output similar to the following with both the arch and environment labels displayed:
code
```
Node Name        Address        Labels
---------------- -------------- ------------------------------------------------------
ip-192-168-13-57 ⟵ Tunnel       arch=x86_64,environment=dev,hostname=ip-192-168-13-57
```

Apply resource-based labels

Applying resource-based labels is only supported for SSH servers.

You can apply resource-based labels to a Teleport SSH server by creating a corresponding server_info resource.

To add resource-based labels first get the SSH server details.

Retrieve the SSH server that you wish to apply labels to. Assign <Var name="node_name" /> to the name of the SSH server:

code

$ tctl get node/<Var name="node_name" />
kind: node
metadata:
  expires: "2024-01-12T00:41:17.355013266Z"
  name: 116b08d2-7167-4eab-85a8-cf93f054b217
spec:
  addr: 127.0.0.1:3022
  hostname: foo

Create the corresponding server_info.yaml for the node above.
yaml
```
# server_info.yaml
kind: server_info
metadata:
   name: si-116b08d2-7167-4eab-85a8-cf93f054b217
spec:
   new_labels:
      "foo": "bar"
```
The metadata.name of the server_info resource must be equivalent to the metadata.name field of the node resource prefixed with si-.

Run the following to create the server_info resource:
code
```
$ tctl create server_info.yaml
```
Verify that you have added the label by running the following command on your local computer. Your Teleport user must be authorized to access the server. Teleport applies labels from server_info resources gradually to prevent strain on the Auth Service in larger clusters, so it may take several minutes for the new labels to appear.
code
```
$ tsh ls
```
You should see output similar to the following with the dynamic/foo label displayed:
code
```
Node Name        Address        Labels
---------------- -------------- ------------------------------------------------------
ip-192-168-13-57 ⟵ Tunnel       dynamic/foo=bar,hostname=ip-192-168-13-57
```

<Admonition type="warning"> All resource-based labels created with `tctl` will have the `dynamic/` prefix. This prefix forbids the label from being used in a role's deny rules. </Admonition>

To update resource-based labels, recreate the server_info resource with updated labels.

Next steps

After you have labeled your resources, you can use the labels when running tsh and tctl commands to filter the resources that the commands return. For more information, see Resource filtering.

You can also use labels to limit the access that users in different roles have to specific classes of resources. For more information, see Teleport Role Templates.