worker Stanza

The worker stanza configures Boundary worker-specific parameters.

  1. worker {
  2.   name = "example-worker"
  3.   description = "An example worker"
  4.   public_addr = "5.1.23.198"
  5. }
  1. worker {  name = "example-worker"  description = "An example worker"  public_addr = "5.1.23.198"}

  • name - Specifies a unique name of this worker within the Boundary cluster. This value can be a direct name string, can refer to a file on disk (file://) from which an name will be read; or an env var (env://) from which the name will be read.

  • description - Specifies a friendly description of this worker.

  • public_addr - Specifies the public host or IP address (and optionally port) at which the worker can be reached by clients for proxying. This defaults to the address of the listener marked for proxy purpose. This is especially useful for cloud environments that do not bind a publicly accessible IP to a NIC on the host directly, such as an Amazon EIP.

  • controllers - A list of hosts/IP addresses and optionally ports for reaching controllers. The port will default to :9201 if not specified.

  • tags - A map of key-value pairs where values are an array of strings. Most commonly used for filtering targets a worker can proxy via worker tags. On SIGHUP, the tags set here will be re-parsed and new values used..

KMS Configuration

Workers require a KMS block designated for worker-auth. This is the KMS configuration for authentication between the workers and controllers and must be present. Example (not safe for production!):

  1.   kms "aead" {
  2.     purpose = "worker-auth"
  3.     aead_type = "aes-gcm"
  4.     key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  5.     key_id = "global_worker-auth"
  6. }
  1.   kms "aead" {    purpose = "worker-auth"    aead_type = "aes-gcm"    key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="    key_id = "global_worker-auth"}

This configuration must be the same for the worker-auth configuration for the controller if you’re running the controller and worker as separate servers.

And optionally, a KMS stanza for configuration encryption purpose:

  1. # Configuration encryption block: decrypts sensitive values in the
  2. # configuration file. See `boundary config [encrypt|decrypt] -h`.
  3. kms "aead" {
  4.   purpose   = "config"`
  5.   aead_type = "aes-gcm"
  6.   key       = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="
  7. }
  1. # Configuration encryption block: decrypts sensitive values in the# configuration file. See `boundary config [encrypt|decrypt] -h`.kms "aead" {  purpose   = "config"`  aead_type = "aes-gcm"  key       = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="}

Boundary supports many kinds of KMS integrations. For a complete guide to all available KMS types, see our KMS documentation.

Complete Configuration Example

  1. listener "tcp" {
  2.     purpose = "proxy"
  3.     tls_disable = true
  4.     address = "127.0.0.1"
  5. }
  7. worker {
  8.   # Name attr must be unique across workers
  9.   name = "demo-worker-1"
  10.   description = "A default worker created demonstration"
  12.   # Workers must be able to reach controllers on :9201
  13.   controllers = [
  14.     "10.0.0.1",
  15.     "10.0.0.2",
  16.     "10.0.0.3",
  17.   ]
  19.   public_addr = "myhost.mycompany.com"
  21.   tags {
  22.     type   = ["prod", "webservers"]
  23.     region = ["us-east-1"]
  24.   }
  25. }
  27. # must be same key as used on controller config
  28. kms "aead" {
  29.     purpose = "worker-auth"
  30.     aead_type = "aes-gcm"
  31.     key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  32.     key_id = "global_worker-auth"
  33. }
  1. listener "tcp" {    purpose = "proxy"    tls_disable = true    address = "127.0.0.1"}
  2. worker {  # Name attr must be unique across workers  name = "demo-worker-1"  description = "A default worker created demonstration"
  3.   # Workers must be able to reach controllers on :9201  controllers = [    "10.0.0.1",    "10.0.0.2",    "10.0.0.3",  ]
  4.   public_addr = "myhost.mycompany.com"
  5.   tags {    type   = ["prod", "webservers"]    region = ["us-east-1"]  }}
  6. # must be same key as used on controller configkms "aead" {    purpose = "worker-auth"    aead_type = "aes-gcm"    key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="    key_id = "global_worker-auth"}