Boundary Docs: Add workers to the domain model

content/boundary/v0.18.x/content/docs/concepts/domain-model/index.mdx

@@ -4,8 +4,8 @@ page_title: Domain model overview
 description: >-
   Learn about using the domain model to organize identity and access management and target resources for secure access. Understand how resources work together.
 # START AUTO GENERATED METADATA, DO NOT EDIT
-created_at: 2023-01-01T00:00:00.000Z
-last_modified: 2023-01-01T00:00:00.000Z
+created_at: 2025-10-29T10:56:20-04:00
+last_modified: 2026-08-11T03:04:26.000Z
 # END AUTO GENERATED METADATA
 ---
 
@@ -53,6 +53,12 @@ The highest-level in Boundary utilizes the concepts of [Roles](/boundary/docs/co
 
 ![](/img/component-relationship.png)
 
+## Workers
+
+The resources described so far make up Boundary's control plane. [Workers][] make up its data plane. A worker is a resource that represents a service that proxies [sessions][] between [users][] and [targets][], which lets you provide access to private resources without exposing the networks they run on.
+
+Workers exist in the global scope only. You register them with the control plane using one of three methods: controller-led, worker-led, or using a shared KMS. You can assign workers tags, and then use those tags in filters on a [target][] or [storage bucket][] to control which workers handle traffic for that resource.
+
 ## Target and host resources
 
 Boundary exposes endpoints to users as [Targets](/boundary/docs/concepts/domain-model/targets). A target is a resource representing a networked service, with an associated set of permissions, that allows a user to connect and interact with Boundary within a single session. A target may contain references to [Host](/boundary/docs/concepts/domain-model/hosts) sources or an address, and [Credential](/boundary/docs/concepts/domain-model/credentials) sources. Users who access a target create an authorized session to its address or one of its host sources with returned credentials from the target’s credential source.
@@ -170,6 +176,12 @@ significant number of resources exist.
   that represents an individual person or entity
   for the purposes of access control.
 
+- **[Worker][]** :
+  A resource
+  that represents a service
+  that proxies [sessions][]
+  between [users][] and [targets][].
+
 ## Next steps
 
 When getting started with Boundary,
@@ -212,5 +224,7 @@ Refer to the [Scopes] section to help you understand the structure of resources
 [targets]: /boundary/docs/concepts/domain-model/targets
 [user]: /boundary/docs/concepts/domain-model/users
 [users]: /boundary/docs/concepts/domain-model/users
+[worker]: /boundary/docs/concepts/domain-model/workers
+[workers]: /boundary/docs/concepts/domain-model/workers
 [permission]: /boundary/docs/concepts/security/permissions
 [permissions]: /boundary/docs/concepts/security/permissions

content/boundary/v0.18.x/content/docs/concepts/domain-model/workers.mdx

@@ -0,0 +1,119 @@
+---
+layout: docs
+page_title: Worker resource
+description: >-
+  Learn about using the worker resource to proxy sessions between users and targets. Understand worker attributes, registration methods, and worker tags.
+# START AUTO GENERATED METADATA, DO NOT EDIT
+created_at: 2026-08-11T03:04:27.000Z
+last_modified: 2026-08-11T03:04:27.000Z
+# END AUTO GENERATED METADATA
+---
+
+# Workers
+
+A worker is a resource that represents a service that proxies [sessions][] between [users][] and [targets][].
+Workers make up Boundary's data plane.
+They create a direct network tunnel between a user and a target, so that you can provide access to private resources without exposing the network they run on.
+
+In addition to proxying sessions, workers can act as a proxy for a controller that needs access to a private service, such as a private Vault environment.
+Workers can also perform SSH protocol decryption for credential injection and [session recording][].
+
+A worker exists in the [global][] scope only.
+A worker's name is optional, unless you register the worker using a KMS, in which case a name is required.
+If you define a name, it must be lowercase and it must be unique within the global scope.
+
+## Worker registration
+
+You must register a worker with the control plane before it can proxy sessions.
+Boundary supports three registration methods:
+
+- **Controller-led** - You create the worker resource first using the `workers:create:controller-led` action, and then provide the resulting activation token to the worker.
+- **Worker-led** - The worker generates an authorization request token, and you submit that token using the `workers:create:worker-led` action.
+- **KMS** - The worker authenticates to its upstream using a shared KMS.
+This method registers the worker automatically the first time it connects.
+
+Workers registered using the controller-led or worker-led methods require an accessible directory on disk, defined by `auth_storage_path`, to store their credentials.
+Workers registered using a KMS re-authenticate each time they connect, so they do not store credentials locally.
+
+The registration method a worker uses determines whether you can manage its `name` and `description` through the API.
+Refer to [Attributes](#attributes) for more information.
+
+For more information about registering workers, refer to [Worker configuration](/boundary/docs/configuration/worker/worker-configuration).
+
+## Attributes
+
+A worker has the following configurable attributes:
+
+- `name` - (Optional) The name of the resource in Boundary.
+If you set a name, it must be lowercase and it must be unique within the global scope.
+You can set the name using the API only for workers that you register using the controller-led or worker-led methods.
+Workers that you register using a KMS require a name, and you must set it in the worker configuration file.
+The name is read-only in the API for those workers.
+- `description` - (Optional) A description of the resource.
+As with the name, you can set the description using the API only for workers that you register using the controller-led or worker-led methods.
+- `scope_id` - (Required) The ID of the scope the worker exists in.
+The value must be `global`.
+- `worker_generated_auth_token` - (Optional) The authorization request token that the worker generates.
+This attribute is required when you register a worker using the worker-led method, and it is not used with the controller-led method.
+
+### Output-only attributes
+
+Boundary populates the following attributes from the worker's configuration file or from the status the worker reports.
+You cannot set them using the API:
+
+- `address` - The address that the worker is reachable at, as sourced from the worker's configuration file.
+- `type` - The worker type, denoted by how the worker authenticates.
+The value is `pki` for workers that you register using the controller-led or worker-led methods, and `kms` for workers that you register using a KMS.
+- `config_tags` - The tags defined in the worker's configuration file.
+- `api_tags` - The tags applied to the worker using the Admin UI, CLI, or API.
+- `canonical_tags` - The deduplicated union of the worker's configuration tags and API tags.
+Boundary uses the canonical tags when it applies worker filters.
+- `last_status_time` - The time the worker daemon last reported its status.
+- `active_connection_count` - The number of [connections][] the worker currently handles.
+- `release_version` - The version of the Boundary binary the worker runs.
+- `directly_connected_downstream_workers` - The IDs of any workers that are directly connected downstream of this worker in a [multi-hop](/boundary/docs/concepts/workers#multi-hop-sessions) configuration.
+- `local_storage_state` - The state of the worker's local disk space.
+Boundary uses this state to determine whether the worker can record sessions or play back recordings.
+The possible values are `available`, `low storage`, `critically low storage`, `out of storage`, `not configured`, and `unknown`.
+- `remote_storage_state` - The permission state of any [storage buckets][] the worker actively uses.
+Boundary reports the overall status of each storage bucket as either `available` or `error`, as well as the state of the individual `read`, `write`, and `delete` permissions.
+
+## Tags
+
+You can assign key/value tags to workers and then use those tags in filters to control which workers handle a given resource.
+For example, you can use tags to ensure that only workers in a specific region proxy sessions to targets in that region, or to designate which workers perform session recording.
+
+Boundary supports two sources of tags:
+
+- Configuration tags, which you define in the worker's configuration file.
+- API tags, which you set on the worker resource using the Admin UI, CLI, or API.
+
+Boundary combines both sources into the worker's canonical tags, and uses the canonical tags when it evaluates the `egress_worker_filter` and `ingress_worker_filter` attributes on a [target][], or the `worker_filter` attribute on a [storage bucket][].
+
+For more information, refer to [Worker tags](/boundary/docs/concepts/filtering/worker-tags).
+
+## Referenced by
+
+- [Session][]
+- [Session recordings][]
+- [Storage bucket][]
+- [Target][]
+
+## Service API docs
+
+The following services are relevant to this resource:
+
+- [Worker service](/boundary/api-docs/worker-service)
+
+[connections]: /boundary/docs/concepts/domain-model/session-connections
+[global]: /boundary/docs/concepts/domain-model/scopes#global
+[session]: /boundary/docs/concepts/domain-model/sessions
+[sessions]: /boundary/docs/concepts/domain-model/sessions
+[session recording]: /boundary/docs/concepts/domain-model/session-recordings
+[session recordings]: /boundary/docs/concepts/domain-model/session-recordings
+[storage bucket]: /boundary/docs/concepts/domain-model/storage-buckets
+[storage buckets]: /boundary/docs/concepts/domain-model/storage-buckets
+[target]: /boundary/docs/concepts/domain-model/targets
+[targets]: /boundary/docs/concepts/domain-model/targets
+[user]: /boundary/docs/concepts/domain-model/users
+[users]: /boundary/docs/concepts/domain-model/users

content/boundary/v0.18.x/data/docs-nav-data.json

@@ -377,6 +377,10 @@
           {
             "title": "Users",
             "path": "concepts/domain-model/users"
+          },
+          {
+            "title": "Workers",
+            "path": "concepts/domain-model/workers"
           }
         ]
       },

content/boundary/v0.19.x/content/docs/domain-model/index.mdx

@@ -5,7 +5,7 @@ description: >-
   Learn about using the domain model to organize identity and access management and target resources for secure access. Understand how resources work together.
 # START AUTO GENERATED METADATA, DO NOT EDIT
 created_at: 2025-10-29T10:56:20-04:00
-last_modified: 2025-10-29T10:56:20-04:00
+last_modified: 2026-08-11T03:04:27.000Z
 # END AUTO GENERATED METADATA
 ---
 
@@ -53,6 +53,12 @@ The highest-level in Boundary utilizes the concepts of [roles](/boundary/docs/do
 
 ![](/img/component-relationship.png)
 
+## Workers
+
+The resources described so far make up Boundary's control plane. [Workers][] make up its data plane. A worker is a resource that represents a service that proxies [sessions][] between [users][] and [targets][], which lets you provide access to private resources without exposing the networks they run on.
+
+Workers exist in the global scope only. You register them with the control plane using one of three methods: controller-led, worker-led, or using a shared KMS. You can assign workers tags, and then use those tags in filters on a [target][] or [storage bucket][] to control which workers handle traffic for that resource.
+
 ## Target and host resources
 
 Boundary exposes endpoints to users as [targets](/boundary/docs/domain-model/targets). A target is a resource representing a networked service, with an associated set of permissions, that allows a user to connect and interact with Boundary within a single session. A target may contain references to [host](/boundary/docs/domain-model/hosts) sources or an address, and [credential](/boundary/docs/domain-model/credentials) sources. Users who access a target create an authorized session to its address or one of its host sources with returned credentials from the target’s credential source.
@@ -180,6 +186,12 @@ significant number of resources exist.
   that represents an individual person or entity
   for the purposes of access control.
 
+- **[Worker][]** :
+  A resource
+  that represents a service
+  that proxies [sessions][]
+  between [users][] and [targets][].
+
 ## Next steps
 
 When getting started with Boundary,
@@ -224,5 +236,7 @@ Refer to the [scopes] section to help you understand the structure of resources
 [targets]: /boundary/docs/domain-model/targets
 [user]: /boundary/docs/domain-model/users
 [users]: /boundary/docs/domain-model/users
+[worker]: /boundary/docs/domain-model/workers
+[workers]: /boundary/docs/domain-model/workers
 [permission]: /boundary/docs/rbac
 [permissions]: /boundary/docs/rbac

content/boundary/v0.19.x/content/docs/domain-model/workers.mdx

@@ -0,0 +1,119 @@
+---
+layout: docs
+page_title: Worker resource
+description: >-
+  Learn about using the worker resource to proxy sessions between users and targets. Understand worker attributes, registration methods, and worker tags.
+# START AUTO GENERATED METADATA, DO NOT EDIT
+created_at: 2026-08-11T03:04:29.000Z
+last_modified: 2026-08-11T03:04:29.000Z
+# END AUTO GENERATED METADATA
+---
+
+# Workers
+
+A worker is a resource that represents a service that proxies [sessions][] between [users][] and [targets][].
+Workers make up Boundary's data plane.
+They create a direct network tunnel between a user and a target, so that you can provide access to private resources without exposing the network they run on.
+
+In addition to proxying sessions, workers can act as a proxy for a controller that needs access to a private service, such as a private Vault environment.
+Workers can also perform SSH protocol decryption for credential injection and [session recording][].
+
+A worker exists in the [global][] scope only.
+A worker's name is optional, unless you register the worker using a KMS, in which case a name is required.
+If you define a name, it must be lowercase and it must be unique within the global scope.
+
+## Worker registration
+
+You must register a worker with the control plane before it can proxy sessions.
+Boundary supports three registration methods:
+
+- **Controller-led** - You create the worker resource first using the `workers:create:controller-led` action, and then provide the resulting activation token to the worker.
+- **Worker-led** - The worker generates an authorization request token, and you submit that token using the `workers:create:worker-led` action.
+- **KMS** - The worker authenticates to its upstream using a shared KMS.
+This method registers the worker automatically the first time it connects.
+
+Workers registered using the controller-led or worker-led methods require an accessible directory on disk, defined by `auth_storage_path`, to store their credentials.
+Workers registered using a KMS re-authenticate each time they connect, so they do not store credentials locally.
+
+The registration method a worker uses determines whether you can manage its `name` and `description` through the API.
+Refer to [Attributes](#attributes) for more information.
+
+For more information about registering workers, refer to [Register workers](/boundary/docs/workers/registration).
+
+## Attributes
+
+A worker has the following configurable attributes:
+
+- `name` - (Optional) The name of the resource in Boundary.
+If you set a name, it must be lowercase and it must be unique within the global scope.
+You can set the name using the API only for workers that you register using the controller-led or worker-led methods.
+Workers that you register using a KMS require a name, and you must set it in the worker configuration file.
+The name is read-only in the API for those workers.
+- `description` - (Optional) A description of the resource.
+As with the name, you can set the description using the API only for workers that you register using the controller-led or worker-led methods.
+- `scope_id` - (Required) The ID of the scope the worker exists in.
+The value must be `global`.
+- `worker_generated_auth_token` - (Optional) The authorization request token that the worker generates.
+This attribute is required when you register a worker using the worker-led method, and it is not used with the controller-led method.
+
+### Output-only attributes
+
+Boundary populates the following attributes from the worker's configuration file or from the status the worker reports.
+You cannot set them using the API:
+
+- `address` - The address that the worker is reachable at, as sourced from the worker's configuration file.
+- `type` - The worker type, denoted by how the worker authenticates.
+The value is `pki` for workers that you register using the controller-led or worker-led methods, and `kms` for workers that you register using a KMS.
+- `config_tags` - The tags defined in the worker's configuration file.
+- `api_tags` - The tags applied to the worker using the Admin UI, CLI, or API.
+- `canonical_tags` - The deduplicated union of the worker's configuration tags and API tags.
+Boundary uses the canonical tags when it applies worker filters.
+- `last_status_time` - The time the worker daemon last reported its status.
+- `active_connection_count` - The number of [connections][] the worker currently handles.
+- `release_version` - The version of the Boundary binary the worker runs.
+- `directly_connected_downstream_workers` - The IDs of any workers that are directly connected downstream of this worker in a [multi-hop](/boundary/docs/workers/multi-hop) configuration.
+- `local_storage_state` - The state of the worker's local disk space.
+Boundary uses this state to determine whether the worker can record sessions or play back recordings.
+The possible values are `available`, `low storage`, `critically low storage`, `out of storage`, `not configured`, and `unknown`.
+- `remote_storage_state` - The permission state of any [storage buckets][] the worker actively uses.
+Boundary reports the overall status of each storage bucket as either `available` or `error`, as well as the state of the individual `read`, `write`, and `delete` permissions.
+
+## Tags
+
+You can assign key/value tags to workers and then use those tags in filters to control which workers handle a given resource.
+For example, you can use tags to ensure that only workers in a specific region proxy sessions to targets in that region, or to designate which workers perform session recording.
+
+Boundary supports two sources of tags:
+
+- Configuration tags, which you define in the worker's configuration file.
+- API tags, which you set on the worker resource using the Admin UI, CLI, or API.
+
+Boundary combines both sources into the worker's canonical tags, and uses the canonical tags when it evaluates the `egress_worker_filter` and `ingress_worker_filter` attributes on a [target][], or the `worker_filter` attribute on a [storage bucket][].
+
+For more information, refer to [Route traffic through a worker](/boundary/docs/workers/worker-tags).
+
+## Referenced by
+
+- [Session][]
+- [Session recordings][]
+- [Storage bucket][]
+- [Target][]
+
+## Service API docs
+
+The following services are relevant to this resource:
+
+- [Worker service](/boundary/api-docs/worker-service)
+
+[connections]: /boundary/docs/domain-model/session-connections
+[global]: /boundary/docs/domain-model/scopes#global
+[session]: /boundary/docs/domain-model/sessions
+[sessions]: /boundary/docs/domain-model/sessions
+[session recording]: /boundary/docs/domain-model/session-recordings
+[session recordings]: /boundary/docs/domain-model/session-recordings
+[storage bucket]: /boundary/docs/domain-model/storage-buckets
+[storage buckets]: /boundary/docs/domain-model/storage-buckets
+[target]: /boundary/docs/domain-model/targets
+[targets]: /boundary/docs/domain-model/targets
+[user]: /boundary/docs/domain-model/users
+[users]: /boundary/docs/domain-model/users

content/boundary/v0.19.x/data/docs-nav-data.json

@@ -2031,6 +2031,10 @@
       {
         "title": "Users",
         "path": "domain-model/users"
+      },
+      {
+        "title": "Workers",
+        "path": "domain-model/workers"
       }
     ]
   },