Manage workers

Manage workers

출처: HashiCorp Boundary docs After you register a worker, you manage it using the boundary workers commands and by signaling the worker process. This page describes the operations you perform over the life of a worker.

List and read workers

Use the following command to list the workers the controller knows about:

$
 boundary workers list

Use the following command to read the details for a worker:

$
 boundary workers read -id w_UJ3Qq63Jx0

Refer to Start and verify a worker for an explanation of the fields these commands return.

Update the name and description

Use the following command to set a name and description on a worker:

$
 boundary workers update -id w_UJ3Qq63Jx0 \

  -name "ingress-worker-1" \

  -description "Ingress worker for the DMZ network"

Boundary returns the updated worker:

Worker information:

  Active Connection Count:   0

  Address:                   10.0.0.10:9202

  Created Time:              Fri, 07 Aug 2026 13:44:30 MDT

  Description:               Ingress worker for the DMZ network

  ID:                        w_UJ3Qq63Jx0

  Last Status Time:          2026-08-07 19:47:02.592774 +0000 UTC

  Local Storage State:       not configured

  Name:                      ingress-worker-1

  Release Version:           Boundary v1.0.0+ent

  Type:                      pki

  Updated Time:              Fri, 07 Aug 2026 13:47:08 MDT

  Version:                   2

Note You cannot use the boundary workers update command on a worker that registered through an external KMS. Boundary reads the name and description values for those workers from the configuration file. To change them, edit the configuration file and restart the worker.

Manage worker tags

Boundary supports two kinds of worker tags:

  • Configuration tags come from the tags stanza in the worker configuration file. You cannot change them using the CLI or the Admin UI.
  • API tags live on the controller. You add, set, and remove them using the CLI, the Admin UI, or the API. The Canonical tags in the worker output combine both kinds. Use the following command to add an API tag:
$
 boundary workers add-worker-tags -id w_UJ3Qq63Jx0 -tag 
"env=production"

Use the following command to replace all API tags on a worker:

$
 boundary workers set-worker-tags -id w_UJ3Qq63Jx0 -tag 
"env=production"
 -tag 
"env=canary"

Use the following command to remove an API tag:

$
 boundary workers remove-worker-tags -id w_UJ3Qq63Jx0 -tag 
"env=canary"

Boundary requires that API tag keys and values are lowercase, regardless of how you add them. An uppercase character in either the key or the value fails with a wt_tagpair_check constraint failed error. Refer to Route traffic through a worker for more information about tagging strategies.

Reload the worker configuration

The SIGHUP signal causes a worker to reload its configuration file. The worker picks up changes to the following values:

  • initial_upstreams
  • tags
  • ssh_known_hosts_path
  • successful_status_grace_period
  • status_call_timeout
  • get_downstream_workers_timeout To change any other value, restart the worker. If the file at ssh_known_hosts_path is missing or unreadable when you reload the worker, the worker logs an error and keeps using the host keys it already loaded. A missing file behaves differently at startup, where it prevents the worker from starting. Refer to Verify SSH host identity. If you run the worker under systemd, reload the service:
$
 sudo systemctl reload boundary-worker

Otherwise, send SIGHUP to the worker process:

$
 pgrep -f 
"boundary server"

59431


$
 kill -SIGHUP 59431

Confirm that the controller sees the change:

$
 boundary workers read -id w_pkx59YrH6g

The Configuration tags reflect the updated worker configuration file:

  Tags:

    Configuration:

      type: ["worker3" "egress" "session-recording"]

    Canonical:

      type: ["worker3" "egress" "session-recording"]

Drain sessions and shut down a worker

The SIGTERM and SIGINT signals start a graceful shutdown. The worker stops accepting new work from the control plane and waits for its active sessions to drain. When you send the first signal, the worker reports that it entered graceful shutdown:

==> Boundary server graceful shutdown triggered, interrupt again to enter shutdown

Note The worker process continues to run while it drains sessions. Send a second SIGTERM or SIGINT to stop the process without waiting for the remaining sessions. If you run the worker under systemd, stop the service:

$
 sudo systemctl stop boundary-worker

The TimeoutStopSec directive in the unit file controls how long systemd waits for sessions to drain before it kills the process.

Upgrade a worker

Complete the following steps to upgrade a worker:

  1. Stop the worker so that it drains its active sessions.
  2. Replace the Boundary binary, or pull the new container image.
  3. Start the worker. The worker keeps its identity across the upgrade, because its credentials persist in the auth_storage_path directory. You do not need to register the worker again. Confirm the new version after the worker reports status:
$
 boundary workers read -id w_UJ3Qq63Jx0 -format json

Check the release_version field in the output.

Decommission a worker

Complete the following steps to remove a worker from your deployment:

  1. If the worker is an upstream for other workers, point those downstream workers at a different upstream first. Use the Directly Connected Downstream Workers field to find them:$ boundary workers read -id w_UJ3Qq63Jx0
  2. Remove any worker filters that reference this worker's tags or name. If a target filter matches no workers, sessions to that target fail.
  3. Stop the worker so that it drains its active sessions.
  4. Delete the worker resource:$ boundary workers delete -id w_UJ3Qq63Jx0 Boundary confirms the deletion:The delete operation completed successfully.
  5. Delete the contents of the worker's auth_storage_path directory on the host. Stop the worker process before you delete the worker resource. If you delete the resource while the process runs, the worker loses its authorization and logs the following error until you stop it:
worker.(Worker).upstreamDialerFunc: unknown, unknown: error #0: node is not yet authorized

To bring the same host back into service, refer to Clean up and re-register a worker. Deleting the resource for a worker that registered through an external KMS does not remove it permanently. The worker registers itself again the next time it starts, and it reclaims the same worker ID. To decommission one of these workers, stop the worker process first, then delete the resource.

Clean up and re-register a worker

A worker stores its credentials in the directory that you set as auth_storage_path. Boundary writes the following entries to that directory:

  • auth_request_token - A file that holds the activation token the worker generates at startup. Boundary deletes this file after the worker registers, because the token is single use.
  • nodecreds - A directory that holds the credentials which identify the worker to its upstream. It remains for as long as the worker exists. When you delete a worker resource, the controller stops recognizing the credentials in nodecreds, but the directory stays on the worker host. A worker that starts with stale credentials does not generate a new activation token, so you cannot register it again until you clear the directory. If you start the worker before you clear the directory, it fails to authenticate and logs a TLS error:
(nodeenrollment.protocol.Dial) errors encountered attempting to create client tls connection:

error handshaking tls connection: remote error: tls: internal error

Warning Clearing the auth_storage_path directory destroys the worker's identity. Boundary assigns a new worker ID when the worker registers again. Update any worker filters that reference the previous worker name. Complete the following steps to return a host to service:

  1. Stop the worker process.
  2. Delete the worker resource, if you have not already:$ boundary workers delete -id w_UJ3Qq63Jx0
  3. Delete the contents of the auth_storage_path directory on the worker host:$ rm -rf /var/lib/boundary/* Note Check the recording_storage_path value in your worker configuration before you run this command. Boundary does not require that directory to sit outside auth_storage_path. If your deployment nests the two, a wildcard delete also removes session recordings that have not finished uploading to the storage bucket. To remove the credentials without touching anything else in the directory, name the entries explicitly:$ rm -rf /var/lib/boundary/auth_request_token /var/lib/boundary/nodecreds
  4. Start the worker. It generates a new activation token and prints it as the Worker Auth Registration Request value:$ boundary server -config=/etc/boundary.d/egress-worker.hcl
  5. Register the worker again using the method you configured it for. Refer to Register workers. Workers that register through an external KMS do not need this procedure. They authenticate with a KMS key instead of stored credentials, so they register themselves again the next time they start.

More information

Refer to the following topics for more information:

  • workers commands
  • Route traffic through a worker
  • Troubleshoot workers