Address review

gravitational · Mar 16, 2022 · 8c133da · 8c133da
1 parent 9d2a2b0
commit 8c133da
Show file tree

Hide file tree

Showing 4 changed files with 66 additions and 56 deletions.
diff --git a/docs/pages/access-controls/guides/impersonation.mdx b/docs/pages/access-controls/guides/impersonation.mdx
@@ -312,23 +312,16 @@ $ tsh login --proxy=teleport.example.com --user=alice --auth=local
 $ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h
 ```
 
-Here is a summary of variables and functions we used in this guide:
-
-<table>
-<tr>
-  <th>Variable or Function</th>
-  <th>Description</th>
-</tr>
-<tr>
-  <td>`user.spec.traits`</td>
-  <td>Access traits of local or SSO user.</td>
-</tr>
-<tr>
-  <td>`contains(list, var)`</td>
-  <td>Checks whether list contains variable</td>
-</tr>
-<tr>
-  <td>`equals(var, var)`</td>
-  <td>Checks whether one variable is equal another</td>
-</tr>
-</table>
+### Filter fields explained
+
+Explanation of the fields used in this guide for the `where` conditions.
+
+| Field                                             | Description                                                    |
+|---------------------------------------------------|----------------------------------------------------------------|
+| `user.spec.traits["<list name>"]`                 | the `list` of traits from a local or SSO user                  |
+| `impersonate_role.metadata.labels["<label key>"]` | the label `value` given label `key` from a role to impersonate |
+| `impersonate_user.metadata.labels["<label key>"]` | the label `value` given label `key` from a user to impersonate |
+
+
+Check out our [predicate language](../../setup/reference/predicate-language.mdx#scoping-allowdeny-rules-in-role-resources) 
+guide for a more in depth explanation of the language.
diff --git a/docs/pages/access-controls/reference.mdx b/docs/pages/access-controls/reference.mdx
@@ -435,3 +435,17 @@ spec:
 
 Refer to the [Second Factor - U2F guide](./guides/u2f.mdx) if you have a cluster
 using the legacy U2F support.
+
+## Filter fields explained
+
+Explanation of the fields used in this guide for the `where` and `filter` conditions.
+
+| Field                      | Description                                         |
+|----------------------------|-----------------------------------------------------|
+| `user.roles`               | the `list` of roles assigned to a user              |
+| `session.participants`     | the `list` of participants from a session recording |
+| `ssh_session.participants` | the `list` of participants from a SSH session       |
+| `user.metadata.name`       | the user's name                                     |
+
+Check out our [predicate language](../setup/reference/predicate-language.mdx#scoping-allowdeny-rules-in-role-resources) 
+guide for a more in depth explanation of the language.
diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx
@@ -1291,7 +1291,7 @@ tctl version
 
 ## Resource Filtering
 
-Both `tsh` and `tctl` allow you to filter node, app, db, and kube resources using the `--search` and `--query` flags.
+Both `tsh` and `tctl` allow you to filter `nodes`, `apps`, `db`, and `kube` resources using the `--search` and `--query` flags.
 
 The `--search` flag performs a simple fuzzy search on resource fields. For example, `--search=mac` searches for resources containing `mac`.
 
@@ -1305,8 +1305,6 @@ $ tsh ls --search=foo,bar labelKey1=labelValue1,labelKey2=labelValue2
 
 ### Filter Examples
 
-The example with filters, searches for nodes with labels with key `env` equal to `staging` and key `os` equal to `mac`.
-
 ```bash
 # List all nodes
 $ tsh ls
@@ -1317,7 +1315,8 @@ $ tsh ls env=staging,os=mac
 # List nodes using search keywords
 $ tsh ls --search=staging,mac
 
-# List nodes using predicate language
+# List nodes using predicate language. This query searches for nodes with labels
+# with key `env` equal to `staging` and key `os` equal to `mac`.
 $ tsh ls --query='labels.env == "staging" && equals(labels.os, "mac")'
 ```
 

diff --git a/docs/pages/setup/reference/predicate-language.mdx b/docs/pages/setup/reference/predicate-language.mdx
@@ -1,49 +1,53 @@
 ---
 title: Predicate Language
-description: How to use predicate language used to define filter conditions.
-h1: Predicate Language
+description: How to use Teleport's predicate language to define filter conditions.
 ---
 
-Predicate language is used to define filter or where condition for select resources.
+Teleport's predicate language is used to define conditions for filtering in resources.
 It is also used as a query language to filter and search through a [list of select resources](#resource-filtering).
 
-The predicate language support slightly differs depending on where it is used as explained in the next sections.
+The predicate language uses a slightly different syntax depending on whether it is used in:
 
-## Defining Filter or Where Conditions in Role Resources
+- [Role resources](#scoping-allowdeny-rules-in-role-resources)
+- [Resource filtering](#resource-filtering)
 
-Some fields in our role resources uses the predicate language:
+## Scoping allow/deny rules in role resources
 
-- [Dynamic Impersonation](../../access-controls/guides/impersonation.mdx#dynamic-impersonation)
-- [RBAC for sessions](../../access-controls/reference.mdx#rbac-for-sessions)
+Some fields in Teleport's role resources use the predicate language to define the scope of a role's permissions:
 
-The language tailored for role resources supports the following operators:
+- [Dynamic Impersonation](../../access-controls/guides/impersonation.mdx#filter-fields-explained)
+- [RBAC for sessions](../../access-controls/reference.mdx#filter-fields-explained)
 
-| Operator | Meaning                                          | Example                                                          |
-|----------|--------------------------------------------------|------------------------------------------------------------------|
-| &&       | and (all conditions must match)                  | `contains(some.field1, "val1") && equals(some.field2, "val2")`   |
-| \|\|     | or  (any one condition should match)             | `contains(some.field, "val1") \|\| contains(some.field, "val2")` |
-| !        | not (used with functions, more about this below) | `!equals(some.field, "val")`                                     |
+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>, "<value>")` | checks if `<value>` is included in the list of strings from `<field>` |
-| `equals(<field>, "<value>")`   | checks if `<value>` is equal to the value from `<field>`              |
+| 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](#resource-filtering)
+## Resource filtering
 
-Both [`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 tailored for filtering resources.
+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.metadata.name                                  | name = "jenkins"        |
+| Short Field    | Actual Field Equivalent                                     | Example                   |
+|----------------|-------------------------------------------------------------|---------------------------|
+| `labels.<key>` | `resource.metadata.labels` + `resource.spec.dynamic_labels` | `labels.env == "staging"` |
+| `name`         | `resource.metadata.name`                                    | `name == "jenkins"`       |
 
 The language supports the following operators:
 
@@ -57,11 +61,11 @@ The language supports the following operators:
 
 The language also supports the following functions:
 
-| Functions (with examples)             | Description                                          |
-|---------------------------------------|------------------------------------------------------|
-| `equals(labels.env, "prod")`          | resources with label key `env` equal to `prod`       |
-| `exists(labels.env)`                  | resources with a label key `env`; value unchecked    |
-| `!exists(labels.env)`                 | resources without a label key `env`; value unchecked |
-| `search("foo", "bar", "some phrase")` | fuzzy match against common resource fields           |
+| 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.