HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Boundary
Boundary Home

You are viewing documentation for version v0.16.x. View latest version.

Worker tags

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 recordings duties.

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:

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, 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:

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.

It is also possible to set the entire tags block or the keys' values within to 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 / file changes slightly depending on how the configuration file is set:

For setting the entire tags block, both the keys and values need to be specified, 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 tags block, 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 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 "webservers" in "/tags/type"

Tip

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".

Example worker filter for targets

Once workers have tags, you can use these tags to control which workers are allowed to manage a given session by specifying worker filter attributes when you configure targets.

The egress_worker_filter attribute controls which workers are used for egress to a target. This is the worker that accesses the target.

The ingress_worker_filterHCP/ENT attribute controls which workers are used for ingress to a target. This is the worker a client connects to when initiating a connection to a target.

Example of a filter configured on a target in the Admin UI:

Example worker filter for Vault credential store

Tags are used to control which workers can manage Vault requests by specifying a worker_filterattribute when configuring credential stores.

This allows the use of private Vault instances with Boundary. Workers deployed in the same network as a private Vault instance can access and relay Vault requests to Boundary controllers.

Tip

A worker that matches the worker filter must exist before you define the Vault credential store, as it will perform the Vault calls needed to set up the credential store with Boundary.

Example of a worker filter configured on a Vault credential store in the Admin UI:

Example worker filter for storage buckets

Enterprise

Storage buckets are used for session recording, which requires HCP Boundary or Boundary Enterprise

Session recording functions are performed by Boundary workers. Workers also store recordings on Boundary storage buckets. When you create Boundary storage buckets, you can use tags to select the workers you prefer to use for session recording responsibilities.

Example of a worker filter configured on a storage bucket in the Admin UI:

Edit this page on GitHub