Fork me on GitHub

Teleport

Predicate Language

Improve

Teleport's predicate language is used to define conditions for filtering in dynamic configuration resources. It is also used as a query language to filter and search through a list of select resources.

The predicate language uses a slightly different syntax depending on whether it is used in:

Scoping allow/deny rules in role resources

Some fields in Teleport's role resources use the predicate language to define the scope of a role's permissions:

When used in role resources, the predicate language supports the following operators:

OperatorMeaningExample
&&and (all conditions must match)contains(field1, field2) && equals(field2, "val")
||or (any one condition should match)contains(field1, field2) || contains(field1, "val2")
!not (used with functions, more about this below)!equals(field1, field2)

The language also supports the following functions:

FunctionsDescription
contains(<field>, <field2>)checks if the value from <field2> is included in the list of strings from <field>
contains(<field>, "<value>")checks if <value> is included in the list of strings from <field>
equals(<field>, <field2>)checks if the value from <field2> is equal to the value from <field>
equals(<field>, "<value>")checks if <value> is equal to the value from <field>

Resource filtering

Both the tsh and tctl CLI tools allow you to filter nodes, applications, databases, and Kubernetes resources using the --query flag. The --query flag allows you to perform more sophisticated searches using the predicate language.

For common resource fields, we defined shortened field names that can easily be accessed by:

Short FieldActual Field EquivalentExample
labels["<key>"]resource.metadata.labels + resource.spec.dynamic_labelslabels["env"] == "staging"
nameresource.metadata.namename == "jenkins"

The language supports the following operators:

OperatorMeaningExample
==equal tolabels["env"] == "prod" or labels[`env`] == "prod"
!=not equal tolabels["env"] != "prod"
&&and (all conditions must match)labels["env"] == "prod" && labels["os"] == "mac"
||or (any one condition should match)labels["env"] == "dev" || labels["env"] == "qa"
!not (used with functions)!equals(labels["env"], "prod")

The language also supports the following functions:

Functions (with examples)Description
equals(labels["env"], "prod")resources with label key env equal to label value prod
exists(labels["env"])resources with a label key env; label value unchecked
!exists(labels["env"])resources without a label key env; label value unchecked
search("foo", "bar", "some phrase")fuzzy match against common resource fields

See some examples of the different ways you can filter resources.