PKI worker configuration

PKI Workers authenticate to Boundary using a certificate-based method, allowing for worker deployment without using a shared KMS.

PKI Workers require an accessible directory defined by auth_storage_path for credential storage.

Example (not safe for production!):

worker {
  auth_storage_path="/boundary/demo-worker-1"
  initial_upstreams = ["10.0.0.1"]
}

Authorization methods

There are two mechanisms that can be used to register a worker to the cluster.

Controller-led authorization flow

In this flow, the operator fetches an activation token from the controller's workers:create:controller-led action (on the CLI, this is via boundary workers create controller-led). That activation token is given to the worker via the controller_generated_activation_token parameter. This can be done either directly or via an env var or file by using env:// or file:// syntax:

worker {
  auth_storage_path="/boundary/demo-worker-1"
  initial_upstreams = ["10.0.0.1"]
  controller_generated_activation_token = "neslat_........."
  # controller_generated_activation_token = "env://ACT_TOKEN"
  # controller_generated_activation_token = "file:///tmp/worker_act_token"
}

Once the worker starts, it reads this token and uses it to authorize to the cluster. Note that this token is one-time-use; it is safe to keep it here even after the worker has successfully authorized and authenticated, as it will be unusable at that point.

Note: If this value is not present at worker startup time and the worker is not authorized, it will print and write out suitable information for the worker-led flow, described below. So long as the worker-led flow has not been used to authorize the worker, if the controller-generated activation token is provided and the worker restarted, it will make use of it.

Worker-led authorization flow

In this flow, the worker prints out an authorization request token to two places: the startup information printed to stdout, and a file called auth_request_token in the base of the configured auth_storage_path. This token can be submitted to a controller at the workers:create:worker-led path; on the CLI this would be via boundary workers create worker-led -worker-generated-auth-token. No values are needed in the configuration file.

KMS configuration

PKI Workers credentials can be encrypted by including an optional KMS stanza with the purpose worker-auth-storage.

Example (not safe for production!):

kms "aead" {
  purpose = "worker-auth-storage"
    aead_type = "aes-gcm"
    key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
    key_id = "worker-auth-storage"
}

Multi-hop sessions ^{HCP only}

You can use the hcp_boundary_cluister_id field to configure PKI workers to connect to your HCP Boundary cluster or the initial_upstreams field to connect directly to other workers, when set to that worker's public_addr field.

A multi-hop session is when two or more workers are connected, and there are multiple “hops” from a worker to the controller. There are no limits on the amount of workers allowed in a multi-hop session configuration.

The multi-hop session introduces the concepts of “upstream” and “downstream” workers. If you view controllers as the “top” of a multi-hop chain, downstream workers reside below a worker in the chain, while upstream workers reside above a worker in the chain. For example, in the diagram below, Worker 2’s upstream is Worker 1, and its downstream is Worker 3.

You can deploy multi-hop workers in scenarios where inbound network traffic is not allowed. A worker in a private network can send outbound communication to its upstream worker, and create a reverse proxy to establish a session.

You can configure target worker filters with multi-hop workers to allow for fine-grained control on which workers handle ingress and egress for session traffic to a target. Ingress worker filters determine which workers you connect with to initiate a session, and egress worker filters determine which workers are used to access targets.

Multi-hop worker requirements

When you configure multi-hop sessions, there is an "ingress" worker, an "egress" worker, and any number of intermediary workers. Ingress, egress, and intermediary workers have the following requirements.

Ingress worker requirements

To proxy target connections, ingress workers require outbound access to the Boundary control plane and inbound access from clients.

Intermediary worker requirements

Intermediary workers require outbound access to an upstream worker. The upstream worker may be an ingress worker or another intermediary worker. Any upstream intermediary worker needs eventual connectivity to an ingress worker via trusted intermediaries.

Intermediary workers also require inbound access from a downstream worker. The downstream worker may be an egress worker or another intermediary worker. Any downstream intermediary worker needs eventual connectivity to an egress worker via trusted intermediaries.

Egress worker requirements

To proxy target connections, egress workers require outbound access to an upstream worker and outbound access to the destination host. Inbound session connections from clients reach the egress worker via reverse proxy; the ingress worker is initiated from the egress worker.

Complete configuration example

listener "tcp" {
    purpose = "proxy"
    tls_disable = true
    address = "127.0.0.1"
}

worker {
  # Path for worker storage. Must be unique across workers
  auth_storage_path="/boundary/demo-worker-1"

  # Workers typically need to reach upstreams on :9201
  initial_upstreams = [
    "10.0.0.1",
    "10.0.0.2",
    "10.0.0.3",
  ]

  public_addr = "myhost.mycompany.com"

  tags {
    type   = ["prod", "webservers"]
    region = ["us-east-1"]
  }
}

# The following KMS config is an example only
# Use a production KMS such as AWS KMS for production installs
kms "aead" {
  purpose = "worker-auth-storage"
    aead_type = "aes-gcm"
    key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
    key_id = "worker-auth-storage"
}

Tutorials

Refer to the Self-Managed Worker Registration with HCP Boundary tutorial to learn how to register and manage PKI workers.

Refer to the Manage Multi-Hop Sessions with HCP Boundary tutorial to learn how to configure a multi-hop session.