| title | description |
|---|---|
Predicate Language |
How to use Teleport's predicate language to define filter conditions. |
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:
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:
| Operator | Meaning | Example |
|---|---|---|
| && | 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:
| Functions | Description |
|---|---|
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> |
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 Field | Actual Field Equivalent | Example |
|---|---|---|
labels["<key>"] |
resource.metadata.labels + resource.spec.dynamic_labels |
labels["env"] == "staging" |
name |
resource.spec.hostname (only applies to server resource) or resource.metadata.name |
name == "jenkins" |
The language supports the following operators:
| Operator | Meaning | Example |
|---|---|---|
| == | equal to | labels["env"] == "prod" or labels[`env`] == "prod" |
| != | not equal to | labels["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.