Register a worker using an external KMS

Register a worker using an external KMS

출처: HashiCorp Boundary docs In the external KMS method, the worker authenticates to its upstream using a key management system (KMS) key that both share. This method registers the worker in addition to authenticating it, so it requires no API call. Use this method for automatic scaling. Workers that use an external KMS store their credentials in memory and generate new ones on restart.

Requirements

Before you register a worker using an external KMS, you must have:

  • A worker configuration file. Refer to Create the worker configuration.
  • Network access from the worker to its upstream controller or worker on port 9201.
  • A KMS key that the worker and its upstream can both access. HashiCorp strongly recommends that you use the KMS of the cloud provider where you deploy your workers, or Vault Transit. The examples on this page use aead keys for readability. Do not use aead keys in production.

Configure the worker name

Workers that register through an external KMS require a name field. The name must be unique across the workers in the Boundary cluster, and it must be all lowercase. Workers that register through an external KMS also accept an optional description field.

worker
 {

  name        
=
 "kms-worker-1"

  description 
=
 "Worker registered with an external KMS"

  public_addr 
=
 "10.0.0.10:9202"

}

Both values can reference a file on disk with file:// or an environment variable with env://. Note You can only set the name and description fields in the configuration file for workers that register through an external KMS. For workers that use the controller-led or worker-led methods, set these values with the boundary workers update command after you register the worker.

Add the worker-auth KMS block

Workers that register through an external KMS require a kms block with the worker-auth purpose. The upstream controller or worker must have a kms block that references the same key and purpose. The following example shows a complete worker configuration: /etc/boundary.d/egress-worker.hcl

disable_mlock 
=
 true

listener
 "tcp"
 {

  address 
=
 "0.0.0.0:9202"

  purpose 
=
 "proxy"

}

worker
 {

  name              
=
 "kms-worker-1"

  description       
=
 "Worker registered with an external KMS"

  public_addr       
=
 "10.0.0.10:9202"

  initial_upstreams 
=
 [
"10.0.0.1:9201"
]

  tags
 {

    type 
=
 [
"prod"
,
 "kms"
]

  }

}

# This key must match the worker-auth key on the upstream controller

kms
 "awskms"
 {

  purpose    
=
 "worker-auth"

  region     
=
 "us-east-1"

  kms_key_id 
=
 "19ec80b0-dfdd-4d97-8164-c6examplekey1"

}

If a controller and worker run as the same server process, you only need one kms block with the worker-auth purpose. Workers that register through an external KMS do not require an auth_storage_path, because the KMS stores credentials in memory.

Start the worker

Start the worker to register it:

$
 boundary server -config=/etc/boundary.d/egress-worker.hcl

The startup output includes the worker-auth KMS type, which confirms that Boundary loaded the worker-auth block:

==> Boundary server configuration:

           [Worker-Auth] Aead Type: aes-gcm

                               Cgo: disabled

                        Listener 1: tcp (addr: "0.0.0.0:9202", max_request_duration: "1m30s", purpose: "proxy")

                         Log Level: info

                             Mlock: supported: true, enabled: false

                           Version: Boundary v1.0.0+ent

          Worker Public Proxy Addr: 10.0.0.10:9202

==> Boundary server started! Log data will stream in below:

Note The startup output also includes a Worker Auth Registration Request value. Workers that register through an external KMS do not use this value. You can ignore it. The worker registers itself and appears in the worker list without any further action.

Verify the registration

Use the following command to confirm that the worker registered:

$
 boundary workers list

Find the worker by the name value you set in the configuration file:

Worker information:

  ID:                        w_bjsVheFxz0

    Version:                 1

    Name:                    kms-worker-1

    Address:                 10.0.0.10:9202

    ReleaseVersion:          Boundary v1.0.0+ent

    Last Status Time:        Fri, 07 Aug 2026 19:48:30 UTC

    Authorized Actions:

      no-op

      read

      delete

      add-worker-tags

      set-worker-tags

      remove-worker-tags

Workers that register through an external KMS do not support the update action, because Boundary reads their name and description values from the configuration file.

Next steps

After you register the worker, you can:

  • Add worker tags to control which sessions the worker proxies.
  • Configure a worker filter on a target, credential store, or storage bucket.
  • Authenticate downstream workers using a separate KMS trust domain. If the worker does not appear in the worker list, refer to Troubleshoot workers.