Meet us at KubeCon + CloudNativeCon: Paris, France - March 19
Book Demo
Teleport logoTry For Free
Fork me on GitHub

Teleport

Add Labels to Resources

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

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. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 15.0.2.

    See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport v15.0.2 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.0.2 go1.21

Proxy version: 15.0.2Proxy: teleport.example.com
  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 14.3.6.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.3.6 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.3.6 go1.21

Proxy version: 14.3.6Proxy: teleport.example.com
  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 15.0.2.

    You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v15.0.2 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.0.2 go1.21

Proxy version: 15.0.2Proxy: teleport.example.com
  • A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.3.6.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.3.6 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.3.6 go1.21

Proxy version: 14.3.6Proxy: teleport.example.com

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 protected]
tctl status

Cluster teleport.example.com

Version 15.0.2

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 host for running the Teleport agent.

  2. Select an edition, then follow the instructions for that edition to install Teleport.

    Teleport Edition

    The following command updates the repository for the package manager on the local operating system and installs the provided Teleport version:

    curl https://goteleport.com/static/install.sh | bash -s 15.0.2

    Add the Teleport repository to your repository list:

    Download Teleport's PGP public key

    sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc

    Source variables about OS version

    source /etc/os-release

    Add the Teleport APT repository for cloud.

    echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

    Provide your Teleport domain to query the latest compatible Teleport version

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

    Update the repo and install Teleport and the Teleport updater

    sudo apt-get update
    sudo apt-get install "teleport-ent=$TELEPORT_VERSION" teleport-ent-updater

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
    sudo yum install -y yum-utils
    sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

    Provide your Teleport domain to query the latest compatible Teleport version

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

    Install Teleport and the Teleport updater

    sudo yum install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use the dnf config manager plugin to add the teleport RPM repo

    sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

    Provide your Teleport domain to query the latest compatible Teleport version

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

    Install Teleport and the Teleport updater

    sudo dnf install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use Zypper to add the teleport RPM repo

    sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

    Provide your Teleport domain to query the latest compatible Teleport version

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

    Install Teleport and the Teleport updater

    sudo zypper install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    OS repository channels

    The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v15 anywhere in the Teleport documentation.

    Channel nameDescription
    stable/<major>Receives releases for the specified major release line, i.e. v15
    stable/cloudRolling channel that receives releases compatible with current Cloud version
    stable/rollingRolling channel that receives all published Teleport releases

    Before installing a teleport binary with a version besides v14, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.

    Teleport uses Semantic Versioning. Version numbers include a major version, minor version, and patch version, separated by dots. When running multiple teleport binaries within a cluster, the following rules apply:

    • Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
    • Servers support clients that are one major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service instance is compatible with 7.x.x agents and 7.x.x tsh, but we don't guarantee that a 9.x.x agent will work with an 8.x.x Proxy Service instance. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
    • Proxy Service instances and agents do not support Auth Service instances that are on an older major version, and will fail to connect to older Auth Service instances by default. You can override version checks by passing --skip-version-check when starting agents and Proxy Service instances.

    Download Teleport's PGP public key

    sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc

    Source variables about OS version

    source /etc/os-release

    Add the Teleport APT repository for v15. You'll need to update this

    file for each major release of Teleport.

    echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v15" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

    sudo apt-get update
    sudo apt-get install teleport-ent

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo apt-get install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for v15. You'll need to update this

    file for each major release of Teleport.

    First, get the major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
    sudo yum install -y yum-utils
    sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v15/teleport.repo")"
    sudo yum install teleport-ent

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo yum install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository for v15. You'll need to update this

    file for each major release of Teleport.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use zypper to add the teleport RPM repo

    sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")
    sudo yum install teleport-ent

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo yum install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for v15. You'll need to update this

    file for each major release of Teleport.

    First, get the major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use the dnf config manager plugin to add the teleport RPM repo

    sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v15/teleport.repo")"

    Install teleport

    sudo dnf install teleport-ent

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo dnf install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use Zypper to add the teleport RPM repo

    sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v15/teleport-zypper.repo")

    Install teleport

    sudo zypper install teleport-ent

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo zypper install teleport-ent-fips

    In the example commands below, update $SYSTEM_ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

    curl https://cdn.teleport.dev/teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-bin.tar.gz.sha256

    <checksum> <filename>

    curl -O https://cdn.teleport.dev/teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-bin.tar.gz
    shasum -a 256 teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-bin.tar.gz

    Verify that the checksums match

    tar -xvf teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-bin.tar.gz
    cd teleport-ent
    sudo ./install

    For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

    curl https://cdn.teleport.dev/teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256

    <checksum> <filename>

    curl -O https://cdn.teleport.dev/teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-fips-bin.tar.gz
    shasum -a 256 teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-fips-bin.tar.gz

    Verify that the checksums match

    tar -xvf teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-fips-bin.tar.gz
    cd teleport-ent
    sudo ./install

    OS repository channels

    The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v15 anywhere in the Teleport documentation.

    Channel nameDescription
    stable/<major>Receives releases for the specified major release line, i.e. v15
    stable/cloudRolling channel that receives releases compatible with current Cloud version
    stable/rollingRolling channel that receives all published Teleport releases

    Add the Teleport repository to your repository list:

    Download Teleport's PGP public key

    sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc

    Source variables about OS version

    source /etc/os-release

    Add the Teleport APT repository for cloud.

    echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

    Provide your Teleport domain to query the latest compatible Teleport version

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

    Update the repo and install Teleport and the Teleport updater

    sudo apt-get update
    sudo apt-get install "teleport-ent=$TELEPORT_VERSION" teleport-ent-updater

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
    sudo yum install -y yum-utils
    sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

    Provide your Teleport domain to query the latest compatible Teleport version

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

    Install Teleport and the Teleport updater

    sudo yum install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use the dnf config manager plugin to add the teleport RPM repo

    sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

    Provide your Teleport domain to query the latest compatible Teleport version

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

    Install Teleport and the Teleport updater

    sudo dnf install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use Zypper to add the teleport RPM repo

    sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

    Provide your Teleport domain to query the latest compatible Teleport version

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

    Install Teleport and the Teleport updater

    sudo zypper install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    OS repository channels

    The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v15 anywhere in the Teleport documentation.

    Channel nameDescription
    stable/<major>Receives releases for the specified major release line, i.e. v15
    stable/cloudRolling channel that receives releases compatible with current Cloud version
    stable/rollingRolling channel that receives all published Teleport releases

    Before installing a teleport binary with a version besides v14, read our compatibility rules to ensure that the binary is compatible with Teleport Enterprise Cloud.

    Teleport uses Semantic Versioning. Version numbers include a major version, minor version, and patch version, separated by dots. When running multiple teleport binaries within a cluster, the following rules apply:

    • Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
    • Servers support clients that are one major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service instance is compatible with 7.x.x agents and 7.x.x tsh, but we don't guarantee that a 9.x.x agent will work with an 8.x.x Proxy Service instance. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
    • Proxy Service instances and agents do not support Auth Service instances that are on an older major version, and will fail to connect to older Auth Service instances by default. You can override version checks by passing --skip-version-check when starting agents and Proxy Service instances.
  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. Copy the token and assign it to an environment variable on the computer you are enrolling as a resource:

    export INVITE_TOKEN=<token>

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 with the invitation token you saved in the INVITE_TOKEN environment variable:

    sudo teleport start --token=${INVITE_TOKEN?}
  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
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.

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.