Boundary
Route traffic through a worker
This page describes how to use worker tags and filters to control which workers are allowed to handle a given resource. You can use filters to control traffic locally. As an example, you can use filters to ensure that traffic going into a public cloud is only handled by workers running within that same cloud. Tags can also be used determine which worker should perform session recording duties.
Refer to Filtering and listing resources for more information about Boundary's filter syntax and best practices.
You can configure worker tags using the worker config file, the Admin UI, the CLI, or the API. Select a tag below to view examples.
Tip
Terraform users should consider tagging workers using the worker config file in conjunction with the Boundary Terraform provider worker resource to register workers.
You can tag workers with a set of key/value tags in their configuration file. The keys and values can be any lower-cased printable value. Each key can have more than one value:
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:
{
"worker": {
"name": "web-prod-us-east-1",
"tags": {
"region": ["us-east-1"],
"type": ["prod", "webservers"]
}
}
}
This is the canonical format, and maps closely to the filter structure. For compatibility with some other systems, you can specify the tags in a pure key=value style:
worker {
name = "web-prod-us-east-1"
tags = ["region=us-east-1", "type=prod", "type=webservers"]
}
In this format you cannot have an equal sign as part of the key.
The entire tags block or the keys' values can also point to an environment variable or filepath in the system, through the env:// and file:// URLs:
worker {
name = "web-prod-us-east-1"
tags = "env://BOUNDARY_ALL_WORKER_TAGS"
}
worker {
name = "web-prod-us-east-1"
tags {
type = "env://BOUNDARY_WORKER_TYPE_TAGS"
region = "file://config/worker/region_tags"
usage = ["admin"]
}
}
Notice that the syntax within the environment variable or file changes depending on how the configuration file is set:
For setting the entire
tagsblock, you must specify both the keys and values in JSON or HCL format:{ "region": ["us-east-1"], "type": ["prod", "webservers"] }region = ["us-east-1"] type = ["prod", "webservers"]For setting the keys' values within the
tagsblock, only a JSON array with the tags intended for the particular key is required:["prod", "webservers"]
Filter workers using tags
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:
{
"name": "web-prod-us-east-1",
"tags": {
"region": ["us-east-1"],
"type": ["production", "webservers"]
}
}
Warning
If an expression fails due to a key not being found within the input data, the worker is not included in the final set. You should ensure that all workers that should match a given filter are populated with tags referenced in the filter string. It is not possible to distinguish between a worker that is not included due to the expression itself and a worker that did not have correct tags.
Filter examples
Following are some examples of using these values in filters that can be applied to targets, Vault credential stores, or storage buckets:
Name regex:
"/name" matches "web-prod-us-east-[12]", which would match workers whose names areweb-prod-us-east-1orweb-prod-us-east-2Region:
"us-east-1" in "/tags/region".Grouping:
("us-east-1" in "/tags/region" and "/name" == "web-prod-us-east-1") or "webservers" in "/tags/type"
Each tag can have multiple values, so you must use the in operator to match values. If you know that you have only one value, an equivalent would be "/tags/key/0" == "value".
Next steps
You can configure a worker filter to control which workers are allowed to manage a given session, act as a Vault credential store, or store session recordings.