mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-01 13:39:37 +08:00
Lisa Kim
bc81db4655
* Predicate expressions using the "name" identifier will now use field "hostname" when `ls` querying for nodes, as expected by the user * Change predicate expression for access request that use name identifier to using the actual json field names
73 lines
4.8 KiB
Plaintext
73 lines
4.8 KiB
Plaintext
---
|
|
title: Predicate Language
|
|
description: 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](#resource-filtering).
|
|
|
|
The predicate language uses a slightly different syntax depending on whether it is used in:
|
|
|
|
- [Role resources](#scoping-allowdeny-rules-in-role-resources)
|
|
- [Resource filtering](#resource-filtering)
|
|
|
|
## 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:
|
|
|
|
- [Dynamic Impersonation](../access-controls/guides/impersonation.mdx#filter-fields)
|
|
- [RBAC for sessions](../access-controls/reference.mdx#filter-fields)
|
|
|
|
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>` |
|
|
|
|
|
|
## Resource filtering
|
|
|
|
Both the [`tsh`](cli.mdx#tsh) and [`tctl`](cli.mdx#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](cli.mdx#filter-examples) of the different ways you can filter resources.
|