Skip to content

docs: Update worker configuration #6118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Dan-Heath wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: Update worker configuration #6118

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 35 additions & 32 deletions website/content/docs/workers/registration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: >-

Workers authenticate to Boundary using an activation token. They require an
accessible directory defined by `auth_storage_path` for credential storage and
rotation. Transport level communication between the worker & Controller is secured through PKI.
rotation. Transport level communication between the worker & controller is secured through PKI.

Example (not safe for production!):

Expand All @@ -22,7 +22,7 @@ worker {

## Authorization methods

There are three mechanisms that can be used to initially register a worker to the cluster, Controller-Led, Worker-Led, and registration through an external KMS.
There are three mechanisms that can be used to initially register a worker to the cluster, controller-led, worker-led, and registration through an external KMS.

### Controller-led authorization flow

Expand All @@ -47,12 +47,16 @@ 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
<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. If the worker-led flow has not been used to
authorize the worker, and the controller-generated activation token is provided
and the worker restarted, it will make use of it.

</Note>

### Worker-led authorization flow

In this flow, the worker prints out an authorization request token to two
Expand All @@ -66,20 +70,20 @@ on the CLI this would be via `boundary workers create worker-led

In this flow, the worker authenticates upstream, either to a controller or worker, using a shared KMS provided by the customer. This mechanism auto-registers the worker in addition to authenticating it, and does not require on-disk storage for credentials since each time it connects, it re-authenticates using the trusted KMS.

Optionally with the Multi-Hop workers feature, trusted Workers can authenticate downstream nodes using a separate KMS.
Optionally with the multi-hop workers feature, trusted workers can authenticate downstream nodes using a separate KMS.

Workers using KMS-led authorization require a `name` field. This specifies a unique name of this worker
within the Boundary cluster and _must be unique across workers_. The `name`
within the Boundary cluster and must be unique across workers. The `name`
value can be:
- a direct name string (must be all lowercase)
- a reference to a file on disk (`file://`) from which the name is read
- an env var (`env://`) from which the name is read.
- a reference to a file on disk (`file://`) from which Boundary reads the name
- an env var (`env://`) from which Boundary reads the name

Workers using KMS-led authorization accept an optional `description` field. The `description` value can
be:
- a direct description string
- a reference to a file on disk (`file://`) from which the name is read
- an env var (`env://`) from which the name is read.
- a reference to a file on disk (`file://`) from which Boundary reads the description
- an env var (`env://`) from which Boundary reads the description

```hcl
worker {
Expand All @@ -89,6 +93,12 @@ worker {
}
```

<Note>

The `name` and `description` fields are not valid configuration fields for workers that use worker-led or controller-led authorization. You can only set these fields through the API and they are only valid for workers that use the [KMS authorization method](/boundary/docs/workers/registration#kms-led-authorization-authentication-flow).

</Note>

Workers using the KMS authorization flow also require a KMS block designated for `worker-auth`. This is the KMS configuration for authentication between the workers and controllers and must be present. Example (not safe for production!):

```hcl
Expand All @@ -104,7 +114,7 @@ The upstream controller or worker must have a `kms` block that references the
same key and purpose. If both a controller and worker are running as the same
server process, only one stanza is needed.

For Multi-Hop workers, It is also possible to specify a `kms` block with the `downstream-worker-auth` purpose. If specified, this will be a separate KMS that can be used for authenticating new downstream nodes. Blocks with this purpose can be specified multiple times. This allows a single upstream node to authenticate with one key to its own upstream (via the `worker-auth` purpose) and then serve as an authenticating upstream to nodes
For multi-hop workers, it is also possible to specify a `kms` block with the `downstream-worker-auth` purpose. If specified, this will be a separate KMS that can be used for authenticating new downstream nodes. Blocks with this purpose can be specified multiple times. This allows a single upstream node to authenticate with one key to its own upstream (via the `worker-auth` purpose) and then serve as an authenticating upstream to nodes
across various networks, each with their own separate KMS system or key:

```hcl
Expand All @@ -129,6 +139,20 @@ key; in production you'd want to use a KMS such as AWS KMS, GCP CKMS, Azure
KeyVault, or HashiCorp Vault. For a complete guide to all available KMS types,
refer to [Data encryption in Boundary](/boundary/docs/secure/encryption/data-encryption).

#### KMS configuration

When using controller or worker-led authentication, a worker’s generated activation token is stored in clear-text on disk. Using an external KMS, a worker's 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"
}
```

## Complete configuration example

```hcl
Expand Down Expand Up @@ -173,25 +197,4 @@ are used to connect to upstream Boundary clusters.
## Resources

For more on how `tags{}` in the above configuration are used to facilitate
routing to the correct target, refer to [Route traffic through a worker](/boundary/docs/workers/worker-tags).


## KMS configuration

When using Controller or Worker-led Authentication, a worker’s generated activation token is stored in clear-text on disk. Using an external KMS, a 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"
}
```

<Note>

The `name` and `description` fields are not valid configuration fields for workers that use worker-led or controller-led authorization. You can only set these fields through the API and they are only valid for workers that use the [KMS authorization method](/boundary/docs/workers/registration#kms-led-authorization-authentication-flow).

</Note>
routing to the correct target, refer to [Route traffic through a worker](/boundary/docs/workers/worker-tags).
8 changes: 8 additions & 0 deletions ...e/content/partials/configuration-reference/workers/common-worker-parameters.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,14 @@ worker {
}
```

- `name` - Specifies a unique name for the worker. The `name` field is not used for controller-led or worker-led registration, but it is required for KMS-led authorization. The name value can be:
- an all lowercase direct name string
- a reference to a file on disk (`file://`) from which Boundary reads the name
- an environment variable (`env://`) from which Boundary reads the name
- `description` - Specifies an optional description of the worker for workers that use KMS-led authorization. The `description` field is not used for controller-led or worker-led registration. The description value can be:
- a direct description string
- a reference to a file on disk (`file://`) from which Boundary reads the description
- an environment variable (`env://`) from which Boundary reads the description
- `public_addr` - Specifies the public host or IP address (and optionally port)
where clients can reach the worker for proxying. By default, it uses the
address of the listener marked for `proxy` purpose. This is useful for cloud
Expand Down
Loading