| title | description |
|---|---|
Labels |
Labeling Teleport resources |
Teleport allows you to add arbitrary key-value pairs to applications, servers,
databases, and other resources in your cluster. You can use these to filter
resources when making queries via tctl and tsh as well as to limit the
resources that Teleport roles can access.
This guide explains how to add labels to Teleport resources.
There are two kinds of labels:
Static labels are hardcoded in a teleport daemon's configuration file and do
not change over time while the teleport process is running. An example of a static
label is a Node's environment, e.g., staging vs. production.
Dynamic labels, also known as label commands, allow you to generate labels
at runtime. The teleport daemon will execute an external command on its host
at a configurable frequency and the output of the command becomes the label's
value.
This is especially useful for decoupling the label's value from your Teleport
configuration. For example, if you start Teleport on an Amazon EC2 instance, you
can set a region label based on a command that sends a request to the EC2
instance metadata API.
This means that you can keep your configuration the same for each Node (and set
the configuration within an Amazon Machine Image) while enabling users to search for Nodes by AWS
region.
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
(!docs/pages/includes/tctl.mdx!)
- A host where you will run a Teleport Node. In this guide, we will apply labels to this Node.
You can label any resource managed by Teleport using the instructions in this guide. See the following guides for how to add resources to a Teleport cluster:
| Guide | Notes on labeling |
|---|---|
| Applications | |
| Databases | Teleport can discover some AWS-hosted databases automatically. In this case, labels will also be automatically applied. |
| Kubernetes clusters | |
| Servers | |
| Windows desktops | Dynamic labels are not supported for Windows desktops. See our Desktop Access documentation for how to label desktops. |
On the host where you will run your Teleport Node, follow the instructions for your environment to install Teleport.
(!docs/pages/includes/install-linux.mdx!)
On your local machine, use the tctl tool to generate an invite token that your
Node will use to join the cluster. In the following example, a new token is
created with a TTL of five minutes:
# Generate a short-lived invitation token for a new node:
$ tctl nodes add --ttl=5m --roles=node
# The invite token: (=presets.tokens.first=)
# You can also list all generated non-expired tokens:
$ tctl tokens ls
# Token Type Expiry Time
# ------------------------ ----------- ---------------
# (=presets.tokens.first=) Node 25 Sep 18 00:21 UTC
Copy the token. On the remote host that you will add to your Teleport cluster as a Node, assign the token to an environment variable:
$ export INVITE_TOKEN=<token>
We will use this in the next step.
You can configure Node labels by editing Teleport's configuration file, then starting Teleport.
On the host where you will run your Node, paste the following content into
/etc/teleport.yaml and adjust it for your environment:
<ScopedBlock scope={["oss", "enterprise"]}>
version: v3
teleport:
# The address of your Auth Service.
auth_server: tele.example.com:3025
# Or, you can also use a Proxy Service
# address, e.g., tele.example.com:443, if your Auth Service is not
# exposed to the internet.
proxy_server: tele.example.com:443
auth_service:
enabled: false
proxy_service:
enabled: false
ssh_service:
enabled: true
# Static labels are simple key/value pairs:
labels:
environment: devversion: v3
teleport:
# Your Teleport Cloud tenant address
proxy_server: mytenant.teleport.sh:443
auth_service:
enabled: false
proxy_service:
enabled: false
ssh_service:
enabled: true
# Static labels are simple key/value pairs:
labels:
environment: devNext, start Teleport with the invite token you created earlier:
$ sudo teleport start --token=${INVITE_TOKEN?}
Verify that you have added the label by running the following on your local machine. Your Teleport user must be authorized to access the Node.
$ tsh ls --query 'labels["environment"]=="dev"'
Node Name Address Labels
------------ ---------- ---------------
bdcb47b87ad6 ⟵ Tunnel environment=dev
First, check the logs for your Node to ensure the SSH Service is running. Your logs should resemble the following:
2022-04-27T14:44:23Z INFO [NODE:1] Service is starting in tunnel mode. service/service.go:1993
2022-04-27T14:44:23Z INFO [PROC:1] The new service has started successfully. Starting syncing rotation status with period 10m0s. service/connect.go:482
2022-04-27T14:44:23Z INFO Service has started successfully. service/service.go:523
2022-04-27T14:44:24Z INFO [NODE:PROX] Connected. addr:172.17.0.2:40184 remote-addr:192.0.2.0:443 leaseID:1 target:teleport.example.com:443 reversetunnel/agent.go:409
Next, ensure that your Teleport user has a login that corresponds to a user on your Node.
Run the following command to get the current logins for your user:
<ScopedBlock scope={["oss", "enterprise"]}>
$ tsh status
> Profile URL: https://teleport.example.com:443
Logged in as: myuser
Cluster: teleport.example.com
Roles: access, editor
Logins: -teleport-nologin-d4bc1dad-ce49-4bbe-925d-a67f8d2d6afe
Kubernetes: enabled
Valid until: 2022-04-27 22:26:50 -0400 EDT [valid for 11h40m0s]
Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty
tsh status
> Profile URL: https://mytenant.teleport.sh:443
Logged in as: myuser
Cluster: mytenant.teleport.sh
Roles: access, editor
Logins: -teleport-nologin-d4bc1dad-ce49-4bbe-925d-a67f8d2d6afe
Kubernetes: enabled
Valid until: 2022-04-27 22:26:50 -0400 EDT [valid for 11h40m0s]
Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty
In this example, -teleport-nologin-d4bc1dad-ce49-4bbe-925d-a67f8d2d6afe means
that no logins have been assigned to the user.
To add logins, retrieve your user configuration as YAML:
# Replace "myuser" with your Teleport username
$ tctl get user/myuser > user.yaml
Edit the logins field for your user. Each login must exist as a user on the
host:
db_users: null
kubernetes_groups: null
kubernetes_users: null
- logins: null
+ logins:
+ - root
windows_logins: null
version: v2Apply your changes:
$ tctl create -f user.yaml
user "myuser" has been updated
Log out of your cluster, then log in again. You should now see your Node when
you run tsh ls.
If you wish to use labels for RBAC purposes but don't want to see the labels
in the UI, you can put them in the hidden namespace by prefixing the label's
key with teleport.hidden/, for example teleport.hidden/account-id.
Before following this step, stop Teleport on your Node.
As with static labels, you can apply dynamic labels by editing the Teleport configuration file.
Edit /etc/teleport.yaml to define a commands array as shown below:
<ScopedBlock scope={["oss", "enterprise"]}>
version: v3
teleport:
auth_server: tele.example.com:3025
auth_service:
enabled: false
proxy_service:
enabled: false
ssh_service:
enabled: "yes"
# Configure dynamic labels using the "commands" field:
commands:
- name: hostname
command: [hostname]
period: 1m0s
- name: arch
command: [uname, -p]
# This setting tells Teleport to execute the command above
# once an hour. This value cannot be less than one minute.
period: 1h0m0sversion: v3
teleport:
proxy_server: mytenant.teleport.sh:443
auth_service:
enabled: false
proxy_service:
enabled: false
ssh_service:
enabled: "yes"
# Configure dynamic labels using the "commands" field:
commands:
- name: hostname
command: [hostname]
period: 1m0s
- name: arch
command: [uname, -p]
# This setting tells Teleport to execute the command above
# once an hour. This value cannot be less than one minute.
period: 1h0m0sNotice that the command setting is an array where the first element
is a valid executable and each subsequent element is an argument.
This is valid syntax:
command: ["/bin/uname", "-m"]This is invalid syntax:
command: ["/bin/uname -m"]If you want to pipe several bash commands together, here's how to do it. Notice
how ' and " are interchangeable, so you can use them for nested quotations.
command: ["/bin/sh", "-c", "uname -a | egrep -o '[0-9]+\\.[0-9]+\\.[0-9]+'"]When configuring a command to generate dynamic labels, the executable named within your command must be the path to a valid file. The executable permission bit must be set and shell scripts must have a shebang line.
Once you have configured your labels, start Teleport with the invite token you created earlier:
$ sudo teleport start --token=${INVITE_TOKEN?}
Verify that you have added the labels by running the following on your local machine. Your Teleport user must be authorized to access the Node.
$ tsh ls
Node Name Address Labels
----------------- ---------- ---------------
ip-192-0-2-0 ⟵ Tunnel arch=x86_64,hostname=ip-172-30-156-233
Try creating another invite token using the tctl nodes add command from earlier
and starting your Node again.
If this doesn't work, delete the directory your Node uses to maintain its state,
/var/lib/teleport, and try again.
Once you have labeled your resources, you can refer to your labels when running
tsh and tctl commands to filter the resources that the commands will query.
For more information, see
Resource filtering.
You can also use labels to limit the access that different roles have to specific classes of resources. For more information, see Teleport Role Templates.