diff --git a/website/content/docs/concepts/filtering/index.mdx b/website/content/docs/concepts/filtering/index.mdx new file mode 100644 index 0000000000..23c12fcd84 --- /dev/null +++ b/website/content/docs/concepts/filtering/index.mdx @@ -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 + == "" + != "" + +// Emptiness checks + is empty + is not empty + +// Contains checks or Substring Matching +"" in +"" not in + contains "" + not contains "" + +// Regular Expression Matching + matches "" + not matches "" +``` + +### 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 + or + +// Logical And - evaluates to true if both sub-expressions do + and + +// Logical Not - evaluates to true if the sub-expression does not +not + +// Grouping - Overrides normal precedence rules +( ) + +// Inspects data to check for a match + +``` + +Standard operator precedence can be expected for the various forms. For example, +the following two expressions would be equivalent. + +```text + and not or + +( and (not )) or +``` + +### Performance + +Filters are executed on the controllers and therefore will consume some amount +of CPU time on the controller. diff --git a/website/content/docs/concepts/filtering/worker-tags.mdx b/website/content/docs/concepts/filtering/worker-tags.mdx new file mode 100644 index 0000000000..2097259dad --- /dev/null +++ b/website/content/docs/concepts/filtering/worker-tags.mdx @@ -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"` diff --git a/website/content/docs/concepts/index.mdx b/website/content/docs/concepts/index.mdx index 7f7fb00658..52d0cdcc17 100644 --- a/website/content/docs/concepts/index.mdx +++ b/website/content/docs/concepts/index.mdx @@ -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. diff --git a/website/content/docs/configuration/worker.mdx b/website/content/docs/configuration/worker.mdx index 35fc9805a9..cd36a6c2eb 100644 --- a/website/content/docs/configuration/worker.mdx +++ b/website/content/docs/configuration/worker.mdx @@ -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 diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index d5a3b5da27..a1164b2c5d 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -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',