Jeff MitchellandIrena Rindos
01fb949d0b
This adds an action to the API that allows pulling out an activation token that can be given to a worker in its config (directly or via env or file). The worker can pass this along with its normal request in place of its normal nonce and the server will automatically accept it. Co-authored-by: Irena Rindos <irenarindos@users.noreply.github.com>
126 lines
3.9 KiB
Plaintext
126 lines
3.9 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 {
|
|
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.
|
|
|
|
# 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]: /docs/configuration/worker/kms-worker
|
|
|
|
## Tutorial
|
|
|
|
Refer to the [Self-Managed Worker Registration with HCP Boundary](https://learn.hashicorp.com/tutorials/boundary/hcp-manage-workers) tutorial to learn how to register and manage PKI workers.
|