diff --git a/website/content/docs/concepts/filtering/worker-tags.mdx b/website/content/docs/concepts/filtering/worker-tags.mdx
index dd553c12d..abbd3423f 100644
--- a/website/content/docs/concepts/filtering/worker-tags.mdx
+++ b/website/content/docs/concepts/filtering/worker-tags.mdx
@@ -5,12 +5,13 @@ description: |-
How to use worker tags to control which workers can handle a given resource.
---
-# Filter worker tags
+# Worker tags
This page describes how to use worker tags and filters to control which workers
-are allowed to handle a given resource. This can be used to control traffic
-locality. As an example, this can be used to ensure that traffic going into a
+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
@@ -40,9 +41,9 @@ As HCL is JSON-compatible, this turns into an input JSON value of:
}
```
-~> **Note:** 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:
+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 {
@@ -75,7 +76,7 @@ worker {
}
```
-Note that the syntax within the environment variable / file changes
+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
@@ -100,7 +101,7 @@ array with the tags intended for the particular key is required:
["prod", "webservers"]
```
-## Workers
+## 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
@@ -111,19 +112,21 @@ nested under `tags` and include a `name` value:
"name": "web-prod-us-east-1",
"tags": {
"region": ["us-east-1"],
- "type": ["prod", "webservers"]
+ "type": ["production", "webservers"]
}
}
```
-~> **Note:** If an expression fails due to a key not being found within the input data,
-the worker is not included in the final set, so ensure that all workers that
-should match a given filter are populated with tags referenced in the filter
-string. As a corollary, 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.
+
-Following are some examples of using these values in filters:
+ 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`
@@ -132,13 +135,16 @@ Following are some examples of using these values in filters:
- Grouping: `("us-east-1" in "/tags/region" and "/name" == "web-prod-us-east-1") or "webservers" in "/tags/type"`
-~> **Note:** Each tag can have multiple values, so the `in` operator must be used to match values.
-If you know that you have only one value, an equivalent would be `"/tags/key/0" == "value"`.
+
-## Target workers
+ 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 optional worker filter attributes
+workers are allowed to manage a given session by specifying worker filter attributes
when you configure [targets](/boundary/docs/concepts/domain-model/targets).
The `egress_worker_filter` attribute controls which workers are used for egress to a target. This is the worker
@@ -148,7 +154,41 @@ The `ingress_worker_filter`HCP/ENT attribute controls which workers a
This is the worker a client connects to when initiating a connection to a target.
-## Vault workers
+
+
+
+Example of a filter configured on a target in the Admin UI:
+
+
+
+
+
+
+
+Example of a filter configured on a target with the CLI:
+
+```
+$ boundary targets update tcp -id tssh_1234567890 -egress-worker-filter='"prod" in "/tags/type"'
+```
+
+
+
+
+Example of a filter configured on a target with Terraform:
+
+```hcl
+resource "boundary_target" "aws-webservers-prod" {
+ type = "ssh"
+ name = "aws-web-prod"
+ description = "AWS EC2 Targets"
+ egress_worker_filter = "\"prod\" in \"/tags/type\""
+}
+```
+
+
+
+
+### Example worker filter for Vault credential store
This feature requires HCP Boundary or Boundary Enterprise
@@ -159,8 +199,94 @@ 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.
- ~> **Note:** A worker that matches the worker filter must exist before defining the Vault credential store, as it
- will perform the Vault calls needed to set up the credential store with Boundary.
+
+
+ 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.
+
+
[workers]: /boundary/docs/configuration/worker/worker-configuration
[credential stores]: /boundary/docs/concepts/domain-model/credential-stores#vault-credential-store-attributes
+
+
+
+
+Example of a worker filter configured on a Vault credential store in the Admin UI:
+
+
+
+
+
+
+
+Example of a worker filter configured on a Vault credential store with the CLI:
+
+```
+$ boundary credential-stores update vault -id csvlt_1234567890 -worker-filter='"vault" in "/tags/type"'
+```
+
+
+
+
+Example of a worker filter configured on a Vault credential store with Terraform:
+
+```hcl
+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
+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:
+
+
+
+
+
+
+
+Example of a worker filter configured on a storage bucket with the CLI:
+
+```
+$ boundary storage-buckets update -id sb_1234567890 -worker-filter='"session-recording" in "/tags/type"'
+```
+
+
+
+
+Example of a worker filter configured on a storage bucket with Terraform:
+
+```hcl
+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
+}
+```
+
+
+
diff --git a/website/public/img/session-rec-worker-filter-dark.png b/website/public/img/session-rec-worker-filter-dark.png
new file mode 100644
index 000000000..d916c18f1
Binary files /dev/null and b/website/public/img/session-rec-worker-filter-dark.png differ
diff --git a/website/public/img/session-rec-worker-filter-light.png b/website/public/img/session-rec-worker-filter-light.png
new file mode 100644
index 000000000..4b9dd48d9
Binary files /dev/null and b/website/public/img/session-rec-worker-filter-light.png differ
diff --git a/website/public/img/target-worker-filter-dark.png b/website/public/img/target-worker-filter-dark.png
new file mode 100644
index 000000000..af13d5b4b
Binary files /dev/null and b/website/public/img/target-worker-filter-dark.png differ
diff --git a/website/public/img/target-worker-filter-light.png b/website/public/img/target-worker-filter-light.png
new file mode 100644
index 000000000..9eaf3af77
Binary files /dev/null and b/website/public/img/target-worker-filter-light.png differ
diff --git a/website/public/img/vault-worker-filter-dark.png b/website/public/img/vault-worker-filter-dark.png
new file mode 100644
index 000000000..6785616cf
Binary files /dev/null and b/website/public/img/vault-worker-filter-dark.png differ
diff --git a/website/public/img/vault-worker-filter-light.png b/website/public/img/vault-worker-filter-light.png
new file mode 100644
index 000000000..4cc01f983
Binary files /dev/null and b/website/public/img/vault-worker-filter-light.png differ