
Teleport
Add Labels to Resources
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- 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
andtsh
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 and dynamic labels
The labels you assign to resources can be static labels or dynamic 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 astaging
orproduction
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.
You can add multiple static and dynamic 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 Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
-
A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.0.0.See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
Please use the latest version of Teleport Enterprise documentation.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: 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 on your administrative workstation
using your current credentials. For example:
tsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.0
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/3. Install Teleport
-
Select a host for running the Teleport agent.
-
Select an edition, then follow the instructions for that edition to install Teleport.
Teleport Edition
- Teleport Team
- Open Source
- Enterprise
- Enterprise Cloud
curl https://goteleport.com/static/install.sh | bash -s 13.3.9Before installing a
teleport
binary with a version besides v13, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.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 1 major version behind, but do not support
clients that are on a newer major version. For example, an 8.x.x Proxy Service
is compatible with 7.x.x resource services and 7.x.x
tsh
, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. 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 Services and resource services do not support Auth Services that are on
an older major version, and will fail to connect to older Auth Services by
default. This behavior can be overridden by passing
--skip-version-check
when starting Proxy Services and resource services.
curl https://goteleport.com/static/install.sh | bash -s 14.0.0Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v14. 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/v14" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-entFor FedRAMP/FIPS-compliant installations, install the
teleport-ent-fips
package instead:sudo apt-get install teleport-ent-fipsSource variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v14. 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-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"sudo yum install teleport-entTip: 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-fipsSource variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository for v14. 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-entTip: 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-fipsSource variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v14. 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/v14/teleport.repo")"Install teleport
sudo dnf install teleport-entTip: 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-fipsSource variables about OS version
source /etc/os-releaseAdd 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/v14/teleport-zypper.repo")Install teleport
sudo zypper install teleport-entFor FedRAMP/FIPS-compliant installations, install the
teleport-ent-fips
package instead:sudo zypper install teleport-ent-fipsIn the example commands below, update
$SYSTEM_ARCH
with the appropriate value (amd64
,arm64
, orarm
). All example commands using this variable will update after one is filled out.curl https://get.gravitational.com/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gzcd teleport-entsudo ./installFor FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
curl https://get.gravitational.com/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./installOS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v14
anywhere in the Teleport documentation.Channel name Description stable/<major>
Receives releases for the specified major release line, i.e. v14
stable/cloud
Rolling channel that receives releases compatible with current Cloud version stable/rolling
Rolling channel that receives all published Teleport releases Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation. -
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=nodeThe invite token: abcd123-insecure-do-not-use-this
-
List all generated non-expired tokens by running the following command:
tctl tokens lsToken Type Labels Expiry Time (UTC)
-------------------------------- ----------- ------ -------------------------------
abcd123-insecure-do-not-use-this Node,Db,App 10 Aug 23 19:49 UTC (4m11s)
-
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/3. 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 thessh_service
section. -
Add the static label key and value. For example, add
environment
as the label key anddev
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 -
Save your changes and close the file.
-
Start Teleport with the invitation token you saved in the
INVITE_TOKEN
environment variable:sudo teleport start --token=${INVITE_TOKEN?} -
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-57Checking 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 statusYou 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-policyIf 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=rootThis example adds the
root
login to themyuser
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
Step 3/3. 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 thessh_service
section. -
Add a
command
array that runs theuname
command with the-p
argument to return the architecture of the host server every one hour.For example, add the
name
,command
, andperiod
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, theuname -p
command is executed every one hour (1h), zero minutes (0m), and zero seconds (0s). This value can't be less than one minute. - The executable must be discoverable in the
-
Save your changes and close the file.
-
Start Teleport with the invitation token you saved in the
INVITE_TOKEN
environment variable: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.
tsh lsYou should see output similar to the following with both the
arch
andenvironment
labels displayed:Node Name Address Labels ---------------- -------------- ------------------------------------------------------ip-192-168-13-57 ⟵ Tunnel arch=x86_64,environment=dev,hostname=ip-192-168-13-57
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.