diff --git a/website/content/docs/workers/registration.mdx b/website/content/docs/workers/registration.mdx index ca38429c20..71b538b13b 100644 --- a/website/content/docs/workers/registration.mdx +++ b/website/content/docs/workers/registration.mdx @@ -14,7 +14,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!): @@ -27,7 +27,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 @@ -52,12 +52,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 + + +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. + + ### Worker-led authorization flow In this flow, the worker prints out an authorization request token to two @@ -71,20 +75,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 { @@ -94,6 +98,12 @@ worker { } ``` + + +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). + + + 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 @@ -109,7 +119,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 @@ -134,6 +144,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 @@ -178,25 +202,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" -} -``` - - - -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). - - +routing to the correct target, refer to [Route traffic through a worker](/boundary/docs/workers/worker-tags). \ No newline at end of file diff --git a/website/content/partials/configuration-reference/workers/common-worker-parameters.mdx b/website/content/partials/configuration-reference/workers/common-worker-parameters.mdx index f22e681f80..4416bbf129 100644 --- a/website/content/partials/configuration-reference/workers/common-worker-parameters.mdx +++ b/website/content/partials/configuration-reference/workers/common-worker-parameters.mdx @@ -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