Node Labels & Executable Commands

In the Teleport ecosystem, Node Labels and Executable Commands serve as metadata and dynamic discovery mechanisms for the SSH service. Labels are key-value pairs assigned to a node to facilitate filtering and role-based access control, while executable commands allow the node to periodically run shell commands and export their output as dynamic labels.

The Ansible role manages these through Jinja2 templates, primarily default_teleport.yaml.j2, allowing administrators to define static metadata or automate the collection of system information like uptime, kernel versions, or custom shell outputs.

Sources: README.md:88-102, defaults/main.yml:71-125

Node Labeling Architecture

Node labels are categorized into two types within the configuration: static labels and dynamic command-based labels. Static labels are defined once and remain constant, while command labels are updated on a defined schedule.

Configuration Data Flow

The following diagram illustrates how Ansible variables are processed into the final Teleport configuration file to define labels and commands.

The workflow ensures that any change in label definitions triggers a configuration update and a service reload.
Sources: tasks/config/main.yml:10-53, tasks/main.yml:51-54

Static Node Labels

Static labels are used for organizational purposes, such as identifying the environment, owner, or application type of a node. By default, the role injects the real_hostname label using the Ansible FQDN.

Sources: defaults/main.yml:71-75, defaults/main.yml:92-95

Implementation Detail

Static labels are passed as a dictionary. When the configuration is rendered, these appear under the ssh_service.labels section of the YAML file.
Sources: README.md:162-164, defaults/main.yml:95

Dynamic Executable Commands

Executable commands allow Teleport nodes to run local scripts or binaries and represent the standard output (STDOUT) as a label. This is useful for monitoring state that changes over time without manual intervention.

Command Structure

Each command entry in the teleport_ssh_commands list requires three specific fields:

1. Name: The key name that will appear as the label in the Teleport UI/API.
2. Command: A list containing the command and its arguments.
3. Period: The frequency of execution (e.g., 1h0m0s, 5m0s).

The diagram shows the internal lifecycle of a dynamic label within the node service.
Sources: defaults/main.yml:97-106, README.md:144-155

Default Examples

The role provides several pre-configured command examples to demonstrate usage:

teleport_ssh_commands:
  - name: hostname
    command: [hostname]
    period: 60m0s
  - name: uptime
    command: [uptime, -p]
    period: 5m0s
  - name: ip-address
    command: ["/bin/sh","-c", "hostname -I | awk '{print $1}'"]
    period: 60m0s

Sources: README.md:144-155, defaults/main.yml:107-111

Persistence and Upgrades

When upgrading Teleport or modifying configurations, the role attempts to preserve existing cluster identity while applying new label/command definitions.

Legacy Configuration Parsing

If a configuration already exists at teleport_config_path, the role slurps and parses it to ensure labels can be updated without losing critical join data like the auth_token or ca_pin.

Summary

Node Labels and Executable Commands provide the primary interface for categorizing and monitoring Teleport-managed infrastructure. By leveraging Ansible's templating system, this role allows for the deployment of standardized labels across entire clusters while maintaining the flexibility to run dynamic scripts that expose real-time system state as searchable metadata.

Sources: README.md:21-25, defaults/main.yml:85-111