Route traffic through a worker
Route traffic through a worker
출처: HashiCorp Boundary docs Boundary worker tags are key-value pairs that identify what a worker is and where it runs. You attach tags in the worker configuration file or through the API, then reference them in a worker filter to control which workers proxy a session, reach a Vault credential store, or store session recordings. As an example, you can use a tag to ensure that traffic going into a public cloud is handled by workers running within that same cloud. 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 lowercase printable value. Each key can have more than one value:
worker
{
name
=
"web-prod-us-east-1"
tags
{
region
=
[
"us-east-1"
]
type
=
[
"webserver"
]
}
}
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"
:
[
"webserver"
]
}
}
}
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=webserver"
]
}
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 tags block, you must specify both the keys and values in JSON or HCL format:{ "region": ["us-east-1"], "type": ["webserver"] } region = ["us-east-1"] type = ["webserver"]
- For setting the keys' values within the tags block, only a JSON array with the tags intended for the particular key is required:["webserver"] You can tag workers with a set of key/value API tags in the Boundary Admin UI. Each key can have more than one value. Boundary requires that API tag keys and values are lowercase. Navigate to the worker's Tags tab to view its tags. The Type column identifies where each tag comes from:
- config tags come from the worker configuration file. You cannot modify them in the Admin UI. To change them, update the configuration file and reload the worker.
- api tags are defined on the Boundary controller. You can add, edit, and remove them in the Admin UI. The following image shows the region and type tags that the worker read from its configuration file: These tags come from the following tags stanza in the worker configuration file:
worker
{
tags
{
region
=
[
"us-east-1"
]
type
=
[
"webserver"
]
}
}
Complete the following steps to add an API tag:
- Navigate to the worker's Tags tab.
- Click the Manage dropdown and then Create New Tags.
- Enter in the tag Key and Value, then click Add.
- Repeat this process for any additional tags. When finished, click Save. The following image shows the same worker after you add an env tag with the value production. Boundary marks the new tag as an api tag, and it appears alongside the tags from the configuration file: A tag key can have more than one value. To add another value to the env key, repeat the steps and enter env as the key again. You can edit or remove an API tag using the options menu at the end of its row. Config tags do not have an options menu, because you cannot change them in the Admin UI. You can tag workers with a set of key/value API tags using the CLI. Each key can have more than one value. Boundary requires that API tag keys and values are lowercase. If you use an uppercase character in either, the controller rejects the request with a wt_tagpair_check constraint failed error. The following example shows a worker that has only configuration tags:
$
boundary workers read -id w_0BNbXUyy8D
Worker information:
Active Connection Count: 0
Address: 10.0.0.10:9202
Created Time: Thu, 16 Jul 2026 09:39:13 MDT
ID: w_0BNbXUyy8D
Last Status Time: 2026-07-22 20:12:33.331817 +0000 UTC
Local Storage State: available
Name: web-prod-us-east-1
Release Version: Boundary v1.0.0+ent
Type: pki
Updated Time: Wed, 22 Jul 2026 14:12:45 MDT
Version: 2
Scope:
ID: global
Name: global
Type: global
Tags:
Configuration:
region: ["us-east-1"]
type: ["webserver"]
Canonical:
region: ["us-east-1"]
type: ["webserver"]
Authorized Actions:
no-op
read
update
delete
add-worker-tags
set-worker-tags
remove-worker-tags
The tags listed under Configuration come from the worker configuration file. You cannot modify config tags using the CLI. To change them, update the configuration file and reload the worker. The Canonical tags show all tags associated with a worker, including configuration tags and API tags. Because this worker has no API tags yet, its canonical tags match its configuration tags. API tags are defined on the Boundary controller, and are not written to the worker's configuration file. You can add an API tag using the boundary workers add-worker-tags command:
$
boundary workers add-worker-tags -id w_0BNbXUyy8D -tag
"env=production"
Worker information:
Active Connection Count: 0
Address: 10.0.0.10:9202
Created Time: Thu, 16 Jul 2026 09:39:13 MDT
ID: w_0BNbXUyy8D
Last Status Time: 2026-07-22 20:12:33.331817 +0000 UTC
Local Storage State: available
Name: web-prod-us-east-1
Release Version: Boundary v1.0.0+ent
Type: pki
Updated Time: Wed, 22 Jul 2026 14:20:31 MDT
Version: 3
Scope:
ID: global
Name: global
Type: global
Tags:
Configuration:
region: ["us-east-1"]
type: ["webserver"]
Api:
env: ["production"]
Canonical:
env: ["production"]
region: ["us-east-1"]
type: ["webserver"]
Authorized Actions:
no-op
read
update
delete
add-worker-tags
set-worker-tags
remove-worker-tags
Notice the worker now has both Configuration and API tags listed, and the summation of both sets is listed under the Canonical tags. A tag key can have multiple values associated with it. To update existing API tags using the CLI, you must use the boundary workers set-worker-tags command. The set-worker-tags command replaces every API tag on the worker, so you must include any existing tags that you want to keep. To add a second value to the env key, set both values:
$
boundary workers set-worker-tags -id w_0BNbXUyy8D -tag
"env=production"
-tag
"env=canary"
Worker information:
Active Connection Count: 0
Address: 10.0.0.10:9202
Created Time: Thu, 16 Jul 2026 09:39:13 MDT
ID: w_0BNbXUyy8D
Last Status Time: 2026-07-22 20:12:33.331817 +0000 UTC
Local Storage State: available
Name: web-prod-us-east-1
Release Version: Boundary v1.0.0+ent
Type: pki
Updated Time: Wed, 22 Jul 2026 14:31:07 MDT
Version: 4
Scope:
ID: global
Name: global
Type: global
Tags:
Configuration:
region: ["us-east-1"]
type: ["webserver"]
Api:
env: ["canary" "production"]
Canonical:
env: ["canary" "production"]
region: ["us-east-1"]
type: ["webserver"]
Authorized Actions:
read
update
delete
add-worker-tags
set-worker-tags
remove-worker-tags
no-op
The env key now has two API values. The updated Canonical tags in the output show all tags associated with a worker, including configuration tags and API tags. You can remove API tags using the Admin UI, CLI, or API. To remove an API tag using boundary workers remove-worker-tags:
$
boundary workers remove-worker-tags -id w_0BNbXUyy8D -tag
"env=canary"
Worker information:
Active Connection Count: 0
Address: 10.0.0.10:9202
Created Time: Thu, 16 Jul 2026 09:39:13 MDT
ID: w_0BNbXUyy8D
Last Status Time: 2026-07-22 20:12:33.331817 +0000 UTC
Local Storage State: available
Name: web-prod-us-east-1
Release Version: Boundary v1.0.0+ent
Type: pki
Updated Time: Wed, 22 Jul 2026 14:38:52 MDT
Version: 5
Scope:
ID: global
Name: global
Type: global
Tags:
Configuration:
region: ["us-east-1"]
type: ["webserver"]
Api:
env: ["production"]
Canonical:
env: ["production"]
region: ["us-east-1"]
type: ["webserver"]
Authorized Actions:
read
update
delete
add-worker-tags
set-worker-tags
remove-worker-tags
no-op
You can add, set, and remove API tags using the workers service. Each request requires the worker's current version value, which Boundary uses to prevent conflicting updates. Note These examples use jq to process the JSON output for readability. First, read the worker to obtain its current version and tags:
$
curl --header
"Content-Type: application/json"
\
--header "Authorization: Bearer $(boundary config get-token)" \
--request GET \
$BOUNDARY_ADDR/v1/workers/w_0BNbXUyy8D | jq
The following API call is an example of adding an API tag to a worker:
$
curl --header
"Content-Type: application/json"
\
--header "Authorization: Bearer $(boundary config get-token)" \
--request POST \
--data '{"version":2,"api_tags":{"env":["production"]}}' \
$BOUNDARY_ADDR/v1/workers/w_0BNbXUyy8D:add-worker-tags | jq
Example output:
{
"id": "w_0BNbXUyy8D",
"scope_id": "global",
"scope": {
"id": "global",
"type": "global",
"name": "global",
"description": "Global Scope"
},
"name": "web-prod-us-east-1",
"created_time": "2026-07-16T15:39:13.331817Z",
"updated_time": "2026-07-22T20:20:31.891800Z",
"version": 3,
"address": "10.0.0.10:9202",
"config_tags": {
"region": ["us-east-1"],
"type": ["webserver"]
},
"api_tags": {
"env": ["production"]
},
"canonical_tags": {
"env": ["production"],
"region": ["us-east-1"],
"type": ["webserver"]
},
"last_status_time": "2026-07-22T20:12:33.331817Z",
"active_connection_count": 0,
"type": "pki",
"release_version": "Boundary v1.0.0+ent",
"local_storage_state": "available",
"authorized_actions": [
"no-op",
"read",
"update",
"delete",
"add-worker-tags",
"set-worker-tags",
"remove-worker-tags"
]
}
The config_tags field lists the tags from the worker configuration file, and the api_tags field lists the tags you added using the API. The canonical_tags field combines both. To replace all API tags on a worker, use the set-worker-tags action:
$
curl --header
"Content-Type: application/json"
\
--header "Authorization: Bearer $(boundary config get-token)" \
--request POST \
--data '{"version":3,"api_tags":{"env":["production","canary"]}}' \
$BOUNDARY_ADDR/v1/workers/w_0BNbXUyy8D:set-worker-tags | jq
To remove an API tag, use the remove-worker-tags action:
$
curl --header
"Content-Type: application/json"
\
--header "Authorization: Bearer $(boundary config get-token)" \
--request POST \
--data '{"version":4,"api_tags":{"env":["canary"]}}' \
$BOUNDARY_ADDR/v1/workers/w_0BNbXUyy8D:remove-worker-tags | jq
Each request increments the worker's version value. Read the worker again to get the current version before you make another request. Refer to the worker service API documentation for the full reference.
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"
:
[
"webserver"
]
}
}
Warning If an expression fails because a key is not found within the input data, Boundary does not include the worker in the final set. You should ensure that all workers that must match a given filter carry the tag keys the filter string references. You cannot distinguish between a worker that the expression excluded and a worker that did not have the 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 are web-prod-us-east-1 or web-prod-us-east-2
- Region: "us-east-1" in "/tags/region".
- Grouping: ("us-east-1" in "/tags/region" and "/name" == "web-prod-us-east-1") or "webserver" 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". If you use the Admin UI, you can have Boundary format a filter from a tag key and value instead of writing the expression yourself. Refer to Generate a filter in the Admin UI.
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.