Configure a worker filter

A Boundary worker filter is a boolean expression that selects which workers can handle a resource. You set filters on targets to control session ingress and egress, on Vault credential stores to reach private Vault clusters, and on storage buckets to choose which workers record sessions. 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".

Refer to Filtering and listing resources for more information about Boundary's filter syntax and best practices.

Before you configure a filter, add tags to your workers. Refer to Route traffic through a worker to learn how to tag a worker.

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.

Generate a filter in the Admin UI

The Admin UI includes a filter generator that formats a filter from a worker tag or a worker name. Use the generator when you want Boundary to construct the filter syntax for you.

The generator appears in the following places in the Admin UI:

On a target, when you select the Workers tab and click Add Worker Filter or Edit Worker Filter.
On a Vault credential store, when you select Vault as the credential store type.
On a storage bucket, in the Worker Filter field.

Dynamic host catalogs also accept a worker filter, but they do not include the generator. You must write those filters yourself.

Complete the following steps to generate a filter:

If the generator is not visible, select Show filter generator.
Select whether you want to format a worker Tag or a worker Name.
Enter the input values for the option you selected:
- For Tag, enter the tag Key and the tag Value.
- For Name, select an Operator, and then enter the worker name as the Value.
Click Copy to copy the Generated result.
Paste the generated filter into the filter editor, and then click Save.

The generator formats the following filters:

Option	Input values	Generated filter
Tag	Key `type`, value `egress`	`"egress" in "/tags/type"`
Tag	Key `region`, value `us-east-1`	`"us-east-1" in "/tags/region"`
Name	Operator `==`, value `egress-worker-1`	`"/name" == "egress-worker-1"`
Name	Operator `matches (regex)`, value `egress-worker-1`	`"/name" matches "egress-worker-1"`
Name	Operator `contains`, value `egress-worker-1`	`"/name" contains "egress-worker-1"`

Note

The generator does not apply the filter for you. You must copy the generated result into the filter editor before you save the filter.

The generator formats one tag or one name at a time. To combine conditions, generate each expression separately, and then join them in the editor using the and and or operators. Refer to Filtering and listing resources for the full filter syntax.

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_filter 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 of a target ingress worker filter

Example of a filter configured on a target with Terraform:

resource "boundary_target" "aws-webservers-prod" {
  type                 = "ssh"
  name                 = "aws-web-prod"
  description          = "AWS EC2 Targets"
  scope_id             = boundary_scope.project.id
  default_port         = 22
  egress_worker_filter = "\"prod\" in \"/tags/type\""
}

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 of a credential store worker filter

Example of a worker filter configured on a Vault credential store with Terraform:

resource "boundary_credential_store_vault" "vault_cred_store" {
  name          = "Vault host credentials"
  address       = "http://127.0.0.1:8200"       # change to Vault address
  token         = "s.0ufRo6XEGU2jOqnIr7OlFYP5"  # change to valid Vault token
  scope_id      = boundary_scope.project.id     # change to target scope
  worker_filter = "\"vault\" in \"/tags/type\"" # change to access private Vault cluster
}

Example worker filter for storage buckets

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:

Example of a storage bucket worker filter

Example of a worker filter configured on a storage bucket with Terraform:

resource "boundary_storage_bucket" "aws_dynamic_credentials_example" {
  name        = "session-recording-storage-bucket"
  scope_id    = boundary_scope.org.id # change to valid scope ID
  plugin_name = "aws"
  bucket_name = "mybucket"            # change to valid AWS S3 storage bucket name

  # the role_arn value should match the arn used as the instance profile attached to the ec2 instance
  # https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html
  attributes_json = jsonencode({
    "region"                      = "us-east-1"
    "role_arn"                    = "arn:aws:iam::123456789012:role/S3Access" # change to valid role ARN
    "disable_credential_rotation" = "true"
  })
  worker_filter = "\"session-recording\" in \"/tags/type\"" # change to valid worker filter tag
}

Next steps

After you configure a worker filter, you can configure multi-hop sessions to chain workers across networks. Multi-hop deployments use ingress and egress filters to route a session through the chain.

You can also verify SSH host identity on the worker that connects to targets.

If a session fails because no workers match the filter, refer to Troubleshoot workers.