boundary/website/content/docs/configuration/worker/pki-worker.mdx

---
layout: docs
page_title: PKI worker configuration
description: |-
  PKI worker-specific parameters.
---

# 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!):

```hcl
worker {
  auth_storage_path="/var/lib/boundary"
  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:

```hcl
worker {
  auth_storage_path="/var/lib/boundary"
  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!):
```hcl
kms "aead" {
  purpose = "worker-auth-storage"
	aead_type = "aes-gcm"
	key = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
	key_id = "worker-auth-storage"
}
```

## Session recording

<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>

[Session recording](/boundary/docs/configuration/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:

```hcl
worker {
  auth_storage_path="/var/lib/boundary"
  initial_upstreams = ["10.0.0.1"]
  recording_storage_path="/local/storage/directory"
}
```

~> **Note:** `name` and `description` fields are not valid config fields for PKI
workers. These fields are only valid for [KMS Workers](/boundary/docs/configuration/worker/kms-worker). `name` and
`description` can only be set for PKI workers through the API.