mirror of https://github.com/hashicorp/boundary
Add initial filtering docs (#898)
* Add initial filtering docs Co-authored-by: Jeff Malnick <malnick@gmail.com>pull/901/head
Jeff Mitchell
5 years ago
committed by
GitHub
parent
ba6c0df8ca
commit
6d2ab34087
@ -0,0 +1,114 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Filtering
|
||||
sidebar_title: Filtering
|
||||
description: |-
|
||||
An introduction to the filtering syntax used in Boundary.
|
||||
---
|
||||
|
||||
# Filtering
|
||||
|
||||
Filter expressions can be used by various parts of Boundary to provide useful
|
||||
functionality. This page describes the overall syntax; see the sub-pages for
|
||||
information on the specific values available for filtering for various features,
|
||||
including examples.
|
||||
|
||||
Each filter expression has matching operators composed with selectors and
|
||||
values.
|
||||
|
||||
## Creating Expressions
|
||||
|
||||
A single expression is a matching operator with a selector and value. They are
|
||||
written in plain text format, and Boolean logic and parenthesization are
|
||||
supported. In general whitespace is ignored, except within literal strings.
|
||||
|
||||
### Matching Operators
|
||||
|
||||
All matching operators use a selector or value to choose what data should be
|
||||
matched. Each endpoint that supports filtering accepts a potentially different
|
||||
list of selectors and is detailed in the API documentation for those endpoints.
|
||||
|
||||
```text
|
||||
// Equality & Inequality checks
|
||||
<Selector> == "<Value>"
|
||||
<Selector> != "<Value>"
|
||||
|
||||
// Emptiness checks
|
||||
<Selector> is empty
|
||||
<Selector> is not empty
|
||||
|
||||
// Contains checks or Substring Matching
|
||||
"<Value>" in <Selector>
|
||||
"<Value>" not in <Selector>
|
||||
<Selector> contains "<Value>"
|
||||
<Selector> not contains "<Value>"
|
||||
|
||||
// Regular Expression Matching
|
||||
<Selector> matches "<Value>"
|
||||
<Selector> not matches "<Value>"
|
||||
```
|
||||
|
||||
### Selectors
|
||||
|
||||
Selectors are used by matching operators to create an expression. Inputs to
|
||||
filter expressions are JSON (or JSON-derived); selectors therefore use [JSON
|
||||
Pointer](https://tools.ietf.org/html/rfc6901) to select values from the input.
|
||||
Each selector must be enclosed in quotes and contain a valid JSON Pointer path,
|
||||
including leading slash (`/`).
|
||||
|
||||
```text
|
||||
// Selects the value `zipzap` from the input `{ "foo": { "bar": "zipzap" } }`
|
||||
"/foo/bar"
|
||||
```
|
||||
|
||||
### Values
|
||||
|
||||
Values are used by matching operators to create an expression. Values can be any
|
||||
valid selector, a number, or a string. It is best practice to quote values.
|
||||
|
||||
Numbers can be base 10 integers or floating point numbers.
|
||||
|
||||
When quoting strings, they may either be enclosed in double quotes or backticks.
|
||||
When enclosed in backticks they are treated as raw strings and escape sequences
|
||||
such as `\n` will not be expanded.
|
||||
|
||||
## Connecting Expressions
|
||||
|
||||
There are several methods for connecting expressions, including
|
||||
|
||||
- Logical `or`
|
||||
- Logical `and`
|
||||
- Logical `not`
|
||||
- Grouping with parenthesis
|
||||
- Matching expressions
|
||||
|
||||
```text
|
||||
// Logical Or - evaluates to true if either sub-expression does
|
||||
<Expression 1> or <Expression 2>
|
||||
|
||||
// Logical And - evaluates to true if both sub-expressions do
|
||||
<Expression 1 > and <Expression 2>
|
||||
|
||||
// Logical Not - evaluates to true if the sub-expression does not
|
||||
not <Expression 1>
|
||||
|
||||
// Grouping - Overrides normal precedence rules
|
||||
( <Expression 1> )
|
||||
|
||||
// Inspects data to check for a match
|
||||
<Matching Expression 1>
|
||||
```
|
||||
|
||||
Standard operator precedence can be expected for the various forms. For example,
|
||||
the following two expressions would be equivalent.
|
||||
|
||||
```text
|
||||
<Expression 1> and not <Expression 2> or <Expression 3>
|
||||
|
||||
( <Expression 1> and (not <Expression 2> )) or <Expression 3>
|
||||
```
|
||||
|
||||
### Performance
|
||||
|
||||
Filters are executed on the controllers and therefore will consume some amount
|
||||
of CPU time on the controller.
|
||||
@ -0,0 +1,87 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Filtering - Worker Tags
|
||||
sidebar_title: Worker Tags
|
||||
description: |-
|
||||
How to use worker tags to control which workers can handle a given target.
|
||||
---
|
||||
|
||||
This page describes how to use worker tags and filters to control which workers
|
||||
are allowed to handle a given target. This can be used to control traffic
|
||||
locality. As an example, this can be used to ensure that traffic going into a
|
||||
public cloud is only handled by workers running within that same cloud.
|
||||
|
||||
# Worker Tags
|
||||
|
||||
Starting in Boundary 0.1.5, a worker can be configured with a set of key/value
|
||||
tags in its configuration file. The keys and values can be any lower-cased
|
||||
printable value. Each key can have more than one value:
|
||||
|
||||
```hcl
|
||||
worker {
|
||||
name = "web-prod-us-east-1"
|
||||
tags {
|
||||
region = ["us-east-1"]
|
||||
type = ["prod", "webservers"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
As HCL is JSON-compatible, this turns into an input JSON value of:
|
||||
|
||||
```json
|
||||
{
|
||||
"worker": {
|
||||
"name": "web-prod-us-east-1",
|
||||
"tags": {
|
||||
"region": ["us-east-1"],
|
||||
"type": ["prod", "webservers"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note that this is the canonical format, as it maps closely to the filter
|
||||
structure. However, for compatibility with some other systems, it is also
|
||||
possible to specify the tags in a pure key=value style:
|
||||
|
||||
```hcl
|
||||
worker {
|
||||
name = "web-prod-us-east-1"
|
||||
tags = ["region=us-east-1", "type=prod", "type=webservers"]
|
||||
}
|
||||
```
|
||||
|
||||
In this format, it is not possible to have an equal sign be a part of the key.
|
||||
|
||||
# Target Worker Filtering
|
||||
|
||||
Once workers have tags, it is possible to use these tags to control which
|
||||
workers are allowed to handle a given session by specifying a `worker_filter`
|
||||
attribute when configuring [targets](/docs/concepts/domain-model/targets).
|
||||
|
||||
As filters operate on JSON Pointer selectors, the values that are input into the
|
||||
filter come from the JSON representation of the values in the configuration file
|
||||
nested under `tags` and include a `name` value:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "web-prod-us-east-1",
|
||||
"tags": {
|
||||
"region": ["us-east-1"],
|
||||
"type": ["prod", "webservers"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Following are some examples of using these values in filters:
|
||||
|
||||
- Name regex: `"/name" matches "web-prod-us-east-[12]"`, which would
|
||||
match workers whose names are `web-prod-us-east-1` or `web-prod-us-east-2`
|
||||
|
||||
- Region: `"us-east-1" in "/tags/region"`. Note that each tag can have multiple
|
||||
values, so it must use the `in` operator to search in the collection. If you
|
||||
know that you have only one value, an equivalent would be `"/tags/region/0" == "us-east-1"`.
|
||||
|
||||
- Grouping: `("us-east-1" in "/tags/region" and "/name" == "web-prod-us-east-1")
|
||||
or "webservers" in "/tags/type"`
|
||||
Loading…
Reference in new issue