Add Labels to Resources

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.

Static, dynamic, and resource-based labels

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

• A running Teleport cluster version 15.4.22 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

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

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. tctl is supported on macOS and Linux machines.

For example:

tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
Cluster  teleport.example.com
Version  15.4.22
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.

Step 1/2. Install Teleport

1. Select a Linux server where you will run a Teleport Agent.

2. Install Teleport on your Linux server:

   1. Assign edition to one of the following, depending on your Teleport edition:

      Edition	Value
      Teleport Enterprise Cloud	cloud
      Teleport Enterprise (Self-Hosted)	enterprise
      Teleport Community Edition	oss

   2. Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:

      TELEPORT_DOMAIN=example.teleport.com
      TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

      Otherwise, get the version of your Teleport cluster:

      TELEPORT_DOMAIN=example.teleport.com
      TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"

   3. Install Teleport on your Linux server:

      curl https://cdn.teleport.dev/install-v15.4.22.sh | bash -s ${TELEPORT_VERSION} edition

      The installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.

3. 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:

   tctl tokens add --ttl=5m --type=node
   The invite token: abcd123-insecure-do-not-use-this

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

   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)

5. Write the join token to a file on the host at /tmp/token:

   echo abcd123-insecure-do-not-use-this | sudo tee /tmp/token

6. 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:

   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:

1. Open the Teleport configuration file, /etc/teleport.yaml, in an editor on the computer where you installed the Teleport Agent.

2. Locate the labels configuration under the ssh_service section.

3. Add the static label key and value. For example, add environment as the label key and dev as the value:

   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:

   ssh_service:  enabled: true  labels:    location: San Francisco Bldg 301 4th floor

4. Save your changes and close the file.

5. Start Teleport on the Linux host:

   Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.

   • Package Manager
   • TAR Archive

   On the host where you will run your Teleport instance, enable and start Teleport:

   sudo systemctl enable teleport
   sudo systemctl start teleport

   On the host where you will run your Teleport instance, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:

   sudo teleport install systemd -o /etc/systemd/system/teleport.service
   sudo systemctl enable teleport
   sudo systemctl start teleport

   You can check the status of your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

6. Verify that you have added the label by running the following command on your local computer.

   tsh ls --query 'labels["environment"]=="dev"'

   You should see output similar to the following:

   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:

   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:

   tsh status

   You should see output similar to the following with at least one login listed for your current user:

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

   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:

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:

1. Stop the Teleport service running on your server.

2. Open the Teleport configuration file—by default, /etc/teleport.yaml—in a text editor.

3. Locate the commands configuration under the ssh_service section.

4. 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:

   ...
   ssh_service:
     enabled: "yes"
     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:

   command: ["/bin/uname", "-m"]
   

   The following syntax is not valid:

   command: ["/bin/uname -m"]
   

   For more complex commands, you can use single (') and double (") quotation marks interchangeably to create nested expressions. For example:

   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.

5. Save your changes and close the file.

6. Start Teleport with the invitation token you saved in the INVITE_TOKEN environment variable:

   sudo teleport start --token=${INVITE_TOKEN?}

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

   tsh ls

   You should see output similar to the following with both the arch and environment labels displayed:

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

You can apply resource-based labels to a Teleport instance by creating a server_info resource for the instance. For a server with name <name>, its matching server_info should be named si-<name>.

To add resource-based labels:

1. Run tctl get node/hostname to get the name of the node resource to apply labels to. You should get output similar to the following:

   kind: node
   metadata:
      expires: "2024-01-12T00:41:17.355013266Z"
      id: <id>
      name: <name-uuid>
      revision: <revision-uuid>
   spec:
      # ...
   

   Save the value of metadata.name for the next step.

2. Create the file server_info.yaml and paste the following into it:

   # server_info.yaml
   kind: server_info
   metadata:
      name: si-<node-name>
   spec:
      new_labels:
         "foo": "bar"
   

   Replace <node-name> with the resource name you saved in the previous step. Run the following to create the server_info resource:

   tctl create server_info.yaml

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

   tsh ls

   You should see output similar to the following with the dynamic/foo label displayed:

   Node Name        Address        Labels                                                                                                                   ---------------- -------------- ------------------------------------------------------ip-192-168-13-57 ⟵ Tunnel       dynamic/foo=bar,hostname=ip-192-168-13-57

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.