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

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

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 and RDP 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 for more information.

For more information about registering workers, refer to Register workers.

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

Referenced by

Service API docs

The following services are relevant to this resource:

Edit this page on GitHub