Configure workers

For Boundary Enterprise, you can configure ingress, intermediary, and egress workers to take advantage of multi-hop worker capabilities.

Note that "ingress," "intermediary," and "egress" are general ways to describe how the respective worker interacts with resources. A worker can serve more than one of those roles at a time. Refer to Multi-hop sessions for more information.

Complete the steps below to configure workers for Boundary Enterprise.

Ingress worker configuration

Create the ingress-worker.hcl file with the relevant configuration information:

# disable memory from being swapped to disk
disable_mlock = true

# listener denoting this is a worker proxy
listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

# worker block for configuring the specifics of the
# worker service
worker {
  public_addr = "<worker_public_addr>"
  initial_upstreams = ["<controller_lb_address>:9201"]
  auth_storage_path = "/var/lib/boundary"
  tags {
    type = ["worker1", "upstream"]
  }
}

# Events (logging) configuration. This
# configures logging for ALL events to both
# stderr and a file at /var/log/boundary/<boundary_use>.log
events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enable = true
  sink "stderr" {
    name = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format = "cloudevents-json"
  }
  sink {
    name = "file-sink"
    description = "All events sent to a file"
    event_types = ["*"]
    format = "cloudevents-json"
    file {
      path = "/var/log/boundary"
      file_name = "ingress-worker.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# kms block for encrypting the authentication PKI material
kms "awskms" {
  purpose    = "worker-auth-storage"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey3"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

Intermediate worker configuration

Create the intermediate-worker.hcl file with the relevant configuration information:

# disable memory from being swapped to disk
disable_mlock = true

# listener denoting this is a worker proxy
listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

# worker block for configuring the specifics of the
# worker service
worker {
  public_addr = "<worker_public_addr>"
  initial_upstreams = ["<ingress_worker_address>:9202"]
  auth_storage_path = "/var/lib/boundary"
  tags {
    type = ["worker2", "intermediate"]
  }
}

# Events (logging) configuration. This
# configures logging for ALL events to both
# stderr and a file at /var/log/boundary/<boundary_use>.log
events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enable = true
  sink "stderr" {
    name = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format = "cloudevents-json"
  }
  sink {
    name = "file-sink"
    description = "All events sent to a file"
    event_types = ["*"]
    format = "cloudevents-json"
    file {
      path = "/var/log/boundary"
      file_name = "intermediate-worker.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# kms block for encrypting the authentication PKI material
kms "awskms" {
  purpose    = "worker-auth-storage"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey4"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

Egress worker configuration

Create the egress-worker.hcl file with the relevant configuration information:

# disable memory from being swapped to disk
disable_mlock = true

# listener denoting this is a worker proxy
listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

# worker block for configuring the specifics of the
# worker service
worker {
  public_addr = "<worker_public_addr>"
  initial_upstreams = ["<intermediate_worker_address>:9202"]
  auth_storage_path = "/var/lib/boundary"
  tags {
    type = ["worker3", "egress"]
  }
}

# Events (logging) configuration. This
# configures logging for ALL events to both
# stderr and a file at /var/log/boundary/<boundary_use>.log
events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enable = true
  sink "stderr" {
    name = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format = "cloudevents-json"
  }
  sink {
    name = "file-sink"
    description = "All events sent to a file"
    event_types = ["*"]
    format = "cloudevents-json"
    file {
      path = "/var/log/boundary"
      file_name = "egress-worker.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# kms block for encrypting the authentication PKI material
kms "awskms" {
  purpose    = "worker-auth-storage"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey5"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

Refer to the list below for explanations of the parameters used in the example above:

• disable mlock (bool: false) - Disables the server from executing the mlock syscall, which prevents memory from being swapped to the disk. This is fine for local development and testing. However, it is not recommended for production unless the systems running Boundary use only encrypted swap or do not use swap at all. Boundary only supports memory locking on UNIX-like systems that support mlock() syscall like Linux and FreeBSD.

  On Linux, to give the Boundary executable the ability to use mlock syscall without running the process as root, run the following command:

  sudo setcap cap_ipc_lock=+ep $(readlink -f $(which boundary))

  If you use a Linux distribution with a modern version of systemd, you can add the following directive to the "[Service]" configuration section:

  LimitMEMLOCK=infinity

• listener - Configures the listeners on which Boundary serves traffic (API cluster and proxy).

• worker - Configures the worker. If present, boundary server starts a worker subprocess.

• events - Configures event-specific parameters.

  The example events configuration above is exhaustive and writes all events to both stderr and a file. This configuration may or may not work for your organization's logging solution.

• kms - Configures KMS blocks for various purposes.

  Refer to the links below for configuration information for the different cloud KMS blocks:

  • AWS
  • Azure
  • GCP
  • OCI
  • AliCloud
  • Vault Transit

Refer to the documentation for additional top-level configuration options and additional controller-specific options.

For the Community Edition of Boundary, you must configure a worker server that communicates with the controller and is responsible for storage-related tasks.

Boundary Community Edition only supports egress workers. To configure workers for multi-hop sessions, check the Boundary Enterprise configuration.

Complete the following steps to configure the worker.

Worker configuration

Create the egress-worker.hcl file with the relevant configuration information:

# disable memory from being swapped to disk
disable_mlock = true

# listener denoting this is a worker proxy
listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

# worker block for configuring the specifics of the
# worker service
worker {
  public_addr = "<worker_public_addr>"
  initial_upstreams = ["<controller_lb_address>:9201"]
  auth_storage_path = "/var/lib/boundary"
  tags {
    type = ["worker", "egress"]
  }
}

# Events (logging) configuration. This
# configures logging for ALL events to both
# stderr and a file at /var/log/boundary/<boundary_use>.log
events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enable = true
  sink "stderr" {
    name = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format = "cloudevents-json"
  }
  sink {
    name = "file-sink"
    description = "All events sent to a file"
    event_types = ["*"]
    format = "cloudevents-json"
    file {
      path = "/var/log/boundary"
      file_name = "egress-worker.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# kms block for encrypting the authentication PKI material
kms "awskms" {
  purpose    = "worker-auth-storage"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey5"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

Refer to the list below for explanations of the parameters used in the example above:

• disable mlock (bool: false) - Disables the server from executing the mlock syscall, which prevents memory from being swapped to the disk. This is fine for local development and testing. However, it is not recommended for production unless the systems running Boundary use only encrypted swap or do not use swap at all. Boundary only supports memory locking on UNIX-like systems that support mlock() syscall like Linux and FreeBSD.

  On Linux, to give the Boundary executable the ability to use mlock syscall without running the process as root, run the following command:

  sudo setcap cap_ipc_lock=+ep $(readlink -f $(which boundary))

  If you use a Linux distribution with a modern version of systemd, you can add the following directive to the "[Service]" configuration section:

  LimitMEMLOCK=infinity

• listener - Configures the listeners on which Boundary serves traffic (API cluster and proxy).

• worker - Configures the worker. If present, boundary server starts a worker subprocess.

• events - Configures event-specific parameters.

  The example events configuration above is exhaustive and writes all events to both stderr and a file. This configuration may or may not work for your organization's logging solution.

• kms - Configures KMS blocks for various purposes.

  Refer to the links below for configuration information for the different cloud KMS blocks:

  • AWS
  • Azure
  • GCP
  • OCI
  • AliCloud
  • Vault Transit

Refer to the documentation for additional top-level configuration options and additional controller-specific options.

Complete the following steps to adopt the worker using the UI:

1. Log in to Boundary as the admin user.

2. Select Workers in the navigation pane.

3. Click New.

4. (Optional) You can use the workers page to construct the contents of the worker.hcl file, if you did not create the configuration file as part of the installation process above. Provide the following details, and Boundary constructs the worker configuration file for you:

   • Boundary Cluster ID
   • Worker Public Address
   • Config file path
   • Worker Tags

5. Scroll to the bottom of the New Worker page, and paste the Worker Auth Registration Request key. Boundary provides you with the Worker Auth Registration Request key in the CLI output when you start the worker. You can also locate this value in the auth_request_token file.

6. Click Register Worker.

7. Click Done.

   The new worker appears on the Workers page.

Complete the following steps to adopt the worker using the CLI:

1. Use the following command to ensure that the BOUNDARY_ADDR is set as an environment variable:

   $ export BOUNDARY_ADDR="https://c3a7a20a-f663-40f3-a8e3-1b2f69b36254.boundary.hashicorp.cloud"
   

2. Log into the CLI as the admin user, providing the Auth Method ID, admin login name, and admin password when prompted.

   $ boundary authenticate password \
     -auth-method-id=ampw_KfLAjMS2CG \
     -login-name=admin
   

   Example:

   $ boundary authenticate password \
     -auth-method-id=ampw_KfLAjMS2CG \
     -login-name=admin
   Please enter the password (it will be hidden):
   
   Authentication information:
     Account ID:      acctpw_r6crEm0FgM
     Auth Method ID:  ampw_KfLAjMS2CG
     Expiration Time: Mon, 27 Jun 2022 22:03:28 MDT
     User ID:         u_ysJd0LXX9T
   
   The token was successfully stored in the chosen keyring and is not displayed here.
   

3. Next, use the following command to export the Worker Auth Request Token value as an environment variable:

   $ export WORKER_TOKEN=<Worker Auth Registration Request Value>
   

   Boundary provides you with the Worker Auth Registration Request key in the CLI output when you start the worker. You can also locate this value in the auth_request_token file.

   The token is used to issue a create worker request that will authorize the worker to Boundary and make it available. Currently worker creation is only supported for Workers with an authorization token(worker-led and controller-led).