Register workers

Before a worker can proxy sessions, it must register with a Boundary controller. Registration establishes the worker as a resource in the global scope and creates the credentials the worker uses to authenticate to its upstream.

All workers use certificates and encryption keys to identify themselves and to protect data in transit. Boundary supports three registration methods so that you can fit worker registration into any workflow.

Compare the registration methods

Method	How it works	Requires an API call	Requires `auth_storage_path`
Controller-led	You generate an activation token on the controller, then place it in the worker configuration file.	Yes, before you start the worker	Yes
Worker-led	The worker generates a registration request, and you submit it to the controller.	Yes, after you start the worker	Yes
External KMS	The worker authenticates using a KMS key that it shares with its upstream.	No	No

Use the following guidance to choose a method:

Controller-led works well when you provision workers using a configuration management tool or an instance template, because you can inject the activation token when you render the configuration file.
Worker-led works well when an operator brings a worker online manually, or when the system that provisions the worker cannot reach the Boundary API.
External KMS works well for automatic scaling, because workers register themselves with no operator action. KMS registration does not require workers to store credentials locally.

Credential storage

Workers that use the controller-led or worker-led methods store their credentials on disk in the directory you define with auth_storage_path. Boundary rotates these credentials automatically. Do not share an auth_storage_path directory between workers.

By default, Boundary does not encrypt the credentials it stores on disk. You can encrypt them by adding a kms block with the worker-auth-storage purpose to the worker configuration file:

kms "awskms" {
  purpose    = "worker-auth-storage"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey5"
}

HashiCorp recommends that you configure a worker-auth-storage key for any worker that uses the controller-led or worker-led method.

Workers that register through an external KMS do not require an auth_storage_path, because they store their credentials in memory and generate new ones on restart.

Register downstream workers

In a multi-hop deployment, a downstream worker connects to an upstream worker instead of connecting directly to a controller. Downstream workers register using the same methods described on this page. The registration request travels up the chain to the controller, so a downstream worker does not require network access to the control plane.

To use a separate KMS trust domain for downstream workers, refer to Authenticate downstream workers.

Next steps

Refer to the following topics to register a worker:

After you register a worker, you can add worker tags to control which sessions it proxies.