Add initial filtering docs (#898)
* Add initial filtering docs Co-authored-by: Jeff Malnick <malnick@gmail.com>
This commit is contained in:
Jeff MitchellandJeff Malnick authored and 
GitHub committed
1 parent
ba6c0df8ca
commit
6d2ab34087
5 files changed
+254
-21
No files matched your search
@@ -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"`
|
||||
@@ -8,25 +8,56 @@ description: |-
|
||||
|
||||
# Concepts
|
||||
|
||||
Boundary is a tool for managing identity-based access for modern, dynamic infrastructure. Just as infrastructure itself can be complex, at first glance Boundary can seem complex as well. As a result, it's helpful to understand how Boundary organizes security principals and resources, as well as how it allows you define granular permissions to those principals. A glossary of terms is contained in the [domain model](/docs/concepts/domain-model) section.
|
||||
Boundary is a tool for managing identity-based access for modern, dynamic
|
||||
infrastructure. Just as infrastructure itself can be complex, at first glance
|
||||
Boundary can seem complex as well. As a result, it's helpful to understand how
|
||||
Boundary organizes security principals and resources, as well as how it allows
|
||||
you define granular permissions to those principals. A glossary of terms is
|
||||
contained in the [domain model](/docs/concepts/domain-model) section.
|
||||
|
||||
# Identity & Permission Management
|
||||
|
||||
Identity is a core concept in Boundary. Identity is represented by two types of resources, mapping to common security principals:
|
||||
Identity is a core concept in Boundary. Identity is represented by two types of
|
||||
resources, mapping to common security principals:
|
||||
|
||||
- [Users](/docs/concepts/domain-model/users), which represent distinct entities that can be tied to authentication accounts
|
||||
- [Groups](/docs/concepts/domain-model/groups), which are collections of Users that allow for easier access management
|
||||
- [Users](/docs/concepts/domain-model/users), which represent distinct entities
|
||||
that can be tied to authentication accounts
|
||||
- [Groups](/docs/concepts/domain-model/groups), which are collections of Users
|
||||
that allow for easier access management
|
||||
|
||||
[Roles](/docs/concepts/domain-model/roles) map users and groups to a set of [grants](/docs/concepts/security/permissions), which provide the ability to perform actions within the system.
|
||||
[Roles](/docs/concepts/domain-model/roles) map users and groups to a set of
|
||||
[grants](/docs/concepts/security/permissions), which provide the ability to
|
||||
perform actions within the system.
|
||||
|
||||
# Resource Management
|
||||
|
||||
Boundary enables flexible management of the hosts and services for which it can broker access. Boundary administrators define [host catalogs](/docs/concepts/domain-model/host-catalogs) that contain information about [hosts](/docs/concepts/domain-model/hosts). These hosts are then collected into [host sets](/docs/concepts/domain-model/host-sets) which represent sets of equivalent hosts. Finally, [targets](/docs/concepts/domain-model/targets) tie together host sets with connection information. Final access to a resource is granted via [roles](/docs/concepts/domain-model/roles) that provide authorization to create sessions against these targets.
|
||||
Boundary enables flexible management of the hosts and services for which it can
|
||||
broker access. Boundary administrators define [host
|
||||
catalogs](/docs/concepts/domain-model/host-catalogs) that contain information
|
||||
about [hosts](/docs/concepts/domain-model/hosts). These hosts are then collected
|
||||
into [host sets](/docs/concepts/domain-model/host-sets) which represent sets of
|
||||
equivalent hosts. Finally, [targets](/docs/concepts/domain-model/targets) tie
|
||||
together host sets with connection information. Final access to a resource is
|
||||
granted via [roles](/docs/concepts/domain-model/roles) that provide
|
||||
authorization to create sessions against these targets.
|
||||
|
||||
# Filtering
|
||||
|
||||
Some parts of Boundary support filters for various purposes. For a description
|
||||
of the filter syntax, see the [filtering](/docs/concepts/filtering) page. See
|
||||
the docs pages for the individual resources or capabilities where filters are
|
||||
supported for the specific inputs and examples with those inputs.
|
||||
|
||||
# Next Steps
|
||||
|
||||
Be sure Boundary is able to run locally with the instructions at [Getting Started](/docs/getting-started). Then, learn how to create targets and initiate a session with [Connect to Your First Target](/docs/getting-started/connect-to-target).
|
||||
Be sure Boundary is able to run locally with the instructions at [Getting
|
||||
Started](/docs/getting-started). Then, learn how to create targets and initiate
|
||||
a session with [Connect to Your First
|
||||
Target](/docs/getting-started/connect-to-target).
|
||||
|
||||
# Further Reading
|
||||
|
||||
For more information see our general recommendations for [deployment architecture](/docs/installing/high-availability), and see the [security model](/docs/concepts/security) documentation for an explanation of the security foundations of Boundary.
|
||||
For more information see our general recommendations for [deployment
|
||||
architecture](/docs/installing/high-availability), and see the [security
|
||||
model](/docs/concepts/security) documentation for an explanation of the security
|
||||
foundations of Boundary.
|
||||
@@ -32,6 +32,8 @@ on the host directly, such as an Amazon EIP.
|
||||
- `controllers` - A list of hosts/IP addresses and optionally ports for reaching
|
||||
controllers. The port will default to :9201 if not specified.
|
||||
|
||||
- `tags` - A map of key-value pairs where values are an array of strings. Most commonly used for [filtering](/docs/concepts/filtering) targets a worker can proxy via [worker tags](/docs/concepts/filtering/worker-tags).
|
||||
|
||||
## KMS Configuration
|
||||
|
||||
Workers require a KMS block designated for `worker-auth`. This is the KMS configuration for
|
||||
@@ -86,6 +88,11 @@ worker {
|
||||
]
|
||||
|
||||
public_addr = "myhost.mycompany.com"
|
||||
|
||||
tags {
|
||||
type = ["prod", "webservers"]
|
||||
region = ["us-east-1"]
|
||||
}
|
||||
}
|
||||
|
||||
# must be same key as used on controller config
|
||||
|
||||
@@ -24,11 +24,7 @@ export default [
|
||||
content: [
|
||||
{
|
||||
category: 'security',
|
||||
content: [
|
||||
'permissions',
|
||||
'data-encryption',
|
||||
'connections-tls',
|
||||
]
|
||||
content: ['permissions', 'data-encryption', 'connections-tls'],
|
||||
},
|
||||
{
|
||||
category: 'domain-model',
|
||||
@@ -46,14 +42,15 @@ export default [
|
||||
'users',
|
||||
],
|
||||
},
|
||||
{
|
||||
category: 'filtering',
|
||||
content: ['worker-tags'],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
category: 'developing',
|
||||
content: [
|
||||
'building',
|
||||
'ui',
|
||||
],
|
||||
content: ['building', 'ui'],
|
||||
},
|
||||
'---',
|
||||
{
|
||||
@@ -61,10 +58,7 @@ export default [
|
||||
content: [
|
||||
{
|
||||
category: 'listener',
|
||||
content: [
|
||||
'tcp',
|
||||
'unix',
|
||||
],
|
||||
content: ['tcp', 'unix'],
|
||||
},
|
||||
{
|
||||
category: 'kms',
|
||||
|
||||
Reference in new issue
Block a user