Register a worker using an external KMS

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

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:

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:

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.