Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[backport v9] Add doc for filter support for CLI tools (#11012) #11258

Merged
merged 1 commit into from
Mar 18, 2022
Merged

[backport v9] Add doc for filter support for CLI tools (#11012) #11258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 12 additions & 20 deletions docs/pages/access-controls/guides/impersonation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -312,23 +312,15 @@ $ 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

Here is an explanation of the fields used in the `where` conditions within this guide.

| Field | Description |
|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| `user.spec.traits["group"]` | The list of traits from a local or SSO user where the `group` trait typically comes from an external identity provider |
| `impersonate_role.metadata.labels["<label key>"]` | The label value given the label `key` from a role to impersonate |
| `impersonate_user.metadata.labels["<label key>"]` | The label value given the 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.
14 changes: 14 additions & 0 deletions docs/pages/access-controls/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Here is an explanation of the fields used in the `where` and `filter` conditions within this guide.

| 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 an 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.
31 changes: 31 additions & 0 deletions docs/pages/setup/reference/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1289,6 +1289,37 @@ Print cluster version:
tctl version
```

## Resource filtering

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`.

The `--query` flag allows you to perform more sophisticated searches using a [predicate language](predicate-language.mdx#resource-filtering).

In both cases, you can further refine the results by appending a list of comma-separated labels to the command. For example:

```bash
$ tsh ls --search=foo,bar labelKey1=labelValue1,labelKey2=labelValue2
```

### Filter Examples

```bash
# List all nodes
$ tsh ls

# List nodes using label argument
$ tsh ls env=staging,os=mac

# List nodes using search keywords
$ tsh ls --search=staging,mac

# 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")'
```

## Experimental features

### tctl access ls
Expand Down
71 changes: 71 additions & 0 deletions docs/pages/setup/reference/predicate-language.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
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.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.