threshold/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 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!):

```hcl
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:

```hcl
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 will read this token and use 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 = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
	key_id = "worker-auth-storage"
}
```

~> **Note:** `name` and `description` fields are not valid config fields for PKI
workers. These fields are only valid for [KMS Workers][]. `name` and
`description` can only be set for PKI workers through the API.

# Multi-Hop Workers<sup>HCP Only</sup>

You can use the `initial_upstreams` field to configure PKI workers to either connect directly to the control plane
or to other workers, when set to the worker's `public_addr`.

A multi-hop configuration 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 configuration.

The multi-hop configuration 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.

![multi-hop workers](/img/multi-hop-workers.png)

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.

# Complete Configuration Example

```hcl
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"
}


```
[kms workers]: /boundary/docs/configuration/worker/kms-worker
[target]: /boundary/docs/concepts/domain-model/targets
[target worker filters]: /boundary/docs/concepts/filtering/worker-tags

## Tutorial

Refer to the [Self-Managed Worker Registration with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-workers) tutorial to learn how to register and manage PKI workers.