PKI worker configuration

PKI Workers authenticate to Boundary using an activation token. They require an accessible directory defined by auth_storage_path for credential storage and rotation.

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 PKI 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 = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
    key_id = "worker-auth-storage"
}

Session recording ^(HCP/ENT)

Session recording requires at least one PKI worker with access to local and remote storage. PKI workers used for session recording require an accessible directory defined by recording_storage_path for storing in-progress session recordings. On session closure, a local session recording is moved to remote storage and deleted locally.

Development example:

worker {
  auth_storage_path="/boundary/demo-worker-1"
  initial_upstreams = ["10.0.0.1"]
  recording_storage_path="/local/storage/directory"
}