Create the worker configuration

A Boundary worker reads its settings from an HCL configuration file that you pass to the boundary server command. The file defines a proxy listener, the upstream that the worker connects to, and the tags that control which sessions it proxies.

Requirements

Before you create the worker configuration, you must have:

• The Boundary binary installed on the host that runs the worker. Refer to Install Boundary.
• The address of the upstream the worker connects to. The upstream is either a controller or another worker.
• Network access from the worker to its upstream on port 9201, and from clients or downstream workers to the worker on port 9202.

Required stanzas

A worker configuration requires the following elements:

• disable_mlock - A top-level parameter that controls whether Boundary can swap memory to disk.
• listener - A listener with the proxy purpose. The worker serves session traffic on this address.
• worker - The worker stanza, which defines the upstream, the storage path, and any tags.

Depending on how you register the worker, you may also need a kms stanza. Refer to Register workers to choose a registration method.

Choose an upstream

Every worker needs one upstream source. Set the upstream using one of the following parameters:

• initial_upstreams - A list of addresses for the controllers or workers that this worker connects to. Use this parameter for self-managed deployments, and for any worker that connects to another worker using multi-hop sessions.
• hcp_boundary_cluster_id - The ID of your HCP Boundary cluster. Use this parameter for a worker that connects directly to HCP Boundary. Set this parameter at the top level of the file, outside the worker stanza.

Initial upstreams and HCPB cluster ID are mutually exclusive fields

Set the worker address

The public_addr parameter specifies the address where clients and downstream workers reach this worker. If you do not set it, Boundary uses the address of the listener that has the proxy purpose.

Set public_addr when the host does not bind a reachable IP address directly to a network interface. An instance behind an Amazon Elastic IP address is one example.

Omit public_addr when a self-managed worker connects to an upstream HCP-managed worker. The self-managed worker initiates that connection, so it does not need a reachable address.

Example configuration

The following example creates a file named egress-worker.hcl. Every deployment has at least one egress worker, which is the worker that connects to targets, so the worker documentation uses that file name for a single-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. Disabling mlock 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 worker-specific options.

Match the tags with a filter

The tags block in the preceding configuration assigns the worker the values worker and egress for the type key. To route a session to this worker, you write a filter that matches one of those values.

The Admin UI can format the filter for you. If you select Tag in the filter generator and enter type as the Key and egress as the Value, the generator returns the following filter:

"egress" in "/tags/type"

You apply the filter to a target, a Vault credential store, or a storage bucket, not to the worker itself. You configure the filter after you start and register the worker, because the filter must match a worker that already reports its tags to the controller.

Refer to Route traffic through a worker for how Boundary uses tags, and to Generate a filter in the Admin UI for the procedure.

Multi-hop configurations

Each worker in a multi-hop chain uses the same configuration structure as the preceding example. The initial_upstreams value points at the worker above it in the chain, and the tags identify the role the worker performs.

Refer to Configure multi-hop sessions for Boundary Enterprise for the ingress, intermediate, and egress worker configurations.

Session recording

If you configure the worker for session recording, add the recording_storage_path and recording_storage_minimum_available_capacity parameters to the worker stanza. Refer to Configure workers for session recording for the requirements.

Next steps

After you create the configuration file, you can start the worker and register it with a controller.

For the full list of worker parameters, refer to the worker stanza documentation.