Dan Heath
d7049e4e79
* docs: Add HCP only to heading * docs: Add worker requirements * docs: Fix heading format and hierarchy * docs: Fix headings format * docs: Update feature name using "sessions" * docs: Fix heading hierarchy * docs: Fix headings format * docs: Fix spacing in title
175 lines
6.8 KiB
Plaintext
175 lines
6.8 KiB
Plaintext
---
|
||
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 sessions <sup>HCP only</sup>
|
||
|
||
You can use the `hcp_boundary_cluster_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
|
||
|
||
```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#target-worker-filtering
|
||
|
||
## 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.
|