CyberCoveLLC/threshold
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge PKI & KMS docs (#4325)

Browse Source 
* Merge PKI & KMS docs

* Update worker-configuration.mdx

remove deprecated kms flag

* docs: Fix TOC

* docs: Create redirects

* docs: Fix some broken links

* modify overview page for post 0.15 changes

* Modify data-encryption docs for post 0.15

* modify configure-workers page for post 0.15

---------

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>
This commit is contained in:
Adam BouhmadandDan Heath authored and GitHub committed 2024-01-30 20:23:26 -05:00
1 parent 27a697f1ce
commit 50de448fee
11 files changed
+262 -290
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

website/content/docs/concepts/domain-model/credential-stores.mdx
+4 -4
View File
@@ -59,11 +59,11 @@ A Vault credential store has the following additional attributes:
A Vault [namespace][]. Requires Vault Enterprise.
- `worker_filter` <sup>HCP/ENT</sup> - (optional)
A [filter] used to control which [PKI workers] can handle Vault requests.
This allows the use of private Vault instances with Boundary. PKI workers
A [filter] used to control which [workers] can handle Vault requests.
This allows the use of private Vault instances with Boundary. Workers
deployed in the same network as a private Vault instance can access and relay
Vault requests to Boundary controllers.
~> **Note:** A PKI worker that matches the worker filter must exist before defining the Vault credential store, as it
~> **Note:** A worker that matches the worker filter must exist before defining the Vault credential store, as it
will perform the Vault calls needed to set up the credential store with Boundary.
### Static credential store attributes
@@ -180,5 +180,5 @@ A static credential store allows user-supplied credentials to be managed by Boun
[renewable]: /vault/api-docs/auth/token#renewable-1
[periodic]: /vault/api-docs/auth/token#token_period
[orphan]: /vault/api-docs/auth/token#orphan
[PKI workers]: /boundary/docs/configuration/worker/pki-worker
[workers]: /boundary/docs/configuration/worker/worker-configuration
[filter]: /boundary/docs/concepts/filtering/worker-tags
website/content/docs/concepts/filtering/worker-tags.mdx
+4 -4
View File
@@ -152,15 +152,15 @@ This is the worker a client connects to when initiating a connection to a target
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
Tags are used to control which [PKI workers] can manage Vault requests by specifying
Tags are used to control which [workers] can manage Vault requests by specifying
a `worker_filter`attribute when configuring [credential stores].
This allows the use of private Vault instances with Boundary. PKI workers
This allows the use of private Vault instances with Boundary. Workers
deployed in the same network as a private Vault instance can access and relay
Vault requests to Boundary controllers.
~> **Note:** A PKI worker that matches the worker filter must exist before defining the Vault credential store, as it
~> **Note:** A worker that matches the worker filter must exist before defining the Vault credential store, as it
will perform the Vault calls needed to set up the credential store with Boundary.
[PKI workers]: /boundary/docs/configuration/worker/pki-worker
[workers]: /boundary/docs/configuration/worker/worker-configuration
[credential stores]: /boundary/docs/concepts/domain-model/credential-stores#vault-credential-store-attributes
website/content/docs/concepts/security/data-encryption.mdx
+6 -6
View File
@@ -15,10 +15,10 @@ Boundary supports and how they are used within the system.
## The `worker-auth-storage` KMS key
The `worker-auth-storage` KMS key is used by a [PKI
Worker](/boundary/docs/configuration/worker/pki-worker) for storage of authentication
keys. It is optional for PKI workers; if not specified the authentication keys
will not be encrypted on disk. This is not used by KMS workers.
The `worker-auth-storage` KMS key can be used by [Workers registered using worker-led or controller-led
methods](/boundary/docs/configuration/worker/worker-configuration) for storage of authentication
keys. It is optional for workers; if not specified the authentication keys
will not be encrypted on disk. This can not used by workers registered using an external KMS.
## The `root` KMS key and per-scope KEK/DEKs <sup>Community Edition only</sup>
@@ -125,8 +125,8 @@ rotate and rewrap the KEKs to complete the migration to the new root key.
The `worker-auth` KMS key is a key shared by the Controller and Worker in order
to authenticate a Worker to the Controller. Specifics of this mechanism can be
found on the [Connections/TLS page](/boundary/docs/concepts/security/connections-tls). If
a worker is used with [PKI
authentication](/boundary/docs/configuration/worker/pki-worker) this is unnecessary.
a worker is registered with [worker-led or controller-led
methods](/boundary/docs/configuration/worker/worker-configuration) this is unnecessary.
## The `recovery` KMS key <sup>Community Edition only</sup>
website/content/docs/configuration/session-recording/create-storage-bucket.mdx
+1 -1
View File
@@ -139,7 +139,7 @@ The worker that you configure for storage must:
- Have access to the AWS S3 storage bucket
- Have an accessible directory defined by `recording_storage_path` for storing session recordings while they are in progress. On session closure, Boundary moves the local session recording to remote storage and deletes the local copy.
- For HCP Boundary, refer to the [Self-managed worker configuration](/hcp/docs/boundary/self-managed-workers/session-recording) documentation.
- For Boundary Enterprise, refer to the refer to the [PKI worker configuration](/boundary/docs/configuration/worker/pki-worker#session-recording) documentation.
- For Boundary Enterprise, refer to the refer to the [worker configuration](/boundary/docs/configuration/worker/worker-configuration#session-recording) documentation.
- Have at least 1 MB of available disk space.
- Run Darwin, Windows, or Linux. The following binaries are not supported for session recording: NetBSD, OpenBSD, Solaris.
website/content/docs/configuration/worker/index.mdx
+15 -21
View File
@@ -10,27 +10,22 @@ description: |-
The `worker` stanza configures Boundary worker-specific parameters.
All workers within Boundary use certificates and encryption keys to identify
themselves and protect data in transit. However, there are multiple different
ways to register them so that registration of workers can fit into any workflow.
Registration methods are referred to as `pki` and `kms` registration methods and
the differences in how they are configured are in the sub-pages linked at the
themselves and protect data in transit. However, there are three different
ways to register them so that registration of workers can fit into any workflow; controller-led, worker-led, and via external KMS.
The differences in how they are configured are in the sub-pages linked at the
bottom of this page.
Workers registered via the `pki` method ("PKI Workers") must be registered in
Workers registered via the worker-led or controller-led methods must be registered in
the system via an API call, and require storage on disk to store the current set
of credentials. Workers registering via the `kms` method ("KMS Workers")
auto-register after successful authentication, making them an easy mechanism to
use for automatic scaling, and meaning they are not required to store
of credentials. Workers registering via an external KMS auto-register after successful authentication, making them an easy mechanism to
use for automatic scaling. This also means they are not required to store
credentials locally; each time they connect the KMS is used to reauthenticate
them.
~> Prior to version 0.13 of Boundary, workers had different properties and
capabilities depending on the registration method. If you are using pre-0.13
workers, with pre-0.13 upstreams please be sure to switch the documentation
version to `0.12.x` for correct information. If you are using 0.13 workers with
KMS-based authentication with pre-0.13 controllers, you _must_ set the
`use_deprecated_kms_auth_method` value in the worker configuration. See the KMS
page for more information.
~> Prior to version 0.15 of Boundary, there were two different types of workers, PKI & KMS workers.
If you are using pre-0.15 workers, with pre-0.15 upstreams please be sure to switch the documentation
version to `0.13.x` - `0.14.x` for correct information.
## Common worker parameters
Regardless of registration mechanism, the following fields are supported.
@@ -80,9 +75,9 @@ worker {
HCP Boundary workers require the [`hcp_boundary_cluster_id`](/boundary/docs/configuration/worker/#hcp_boundary_cluster_id) parameter instead of `initial upstreams`.
If you configure an HCP worker with `initial_upstreams`, the worker configuration fails.
- `hcp_boundary_cluster_id` - A string that you must use to configure PKI workers
- `hcp_boundary_cluster_id` - A string required to configure workers using worker-led or controller-led registration
to connect to your HCP Boundary cluster rather than specifying
`initial_upstreams`. This parameter is currently only valid for workers using the PKI
`initial_upstreams`. This parameter is currently only valid for workers using the worker-led or controller-led
registration method and for workers directly connected to HCP Boundary.
- `recording_storage_path` - A path to the local storage for recorded sessions.
@@ -166,7 +161,7 @@ listener "tcp" {
}
worker {
# Path for worker storage, assuming PKI registration. Must be unique across workers
# Path for worker storage, assuming worker-led or controller-led registration. Must be unique across workers
auth_storage_path="/boundary/demo-worker-1"
# Local storage path required if session recording is enabled
@@ -201,12 +196,11 @@ kms "aead" {
## Tutorials
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.
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 Workers.
Refer to the [Manage Multi-Hop Sessions with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-multi-hop) tutorial to learn how to configure a multi-hop session.
[kms workers]: /boundary/docs/configuration/worker/kms-worker
[pki workers]: /boundary/docs/configuration/worker/pki-worker
[Worker Configuration Methods]: /boundary/docs/configuration/worker/worker-configuration
[target]: /boundary/docs/concepts/domain-model/targets
[target worker filters]: /boundary/docs/concepts/filtering/worker-tags#target-worker-filtering
[session recording]: /boundary/docs/configuration/session-recording
website/content/docs/configuration/worker/kms-worker.mdx
-136
View File
@@ -1,136 +0,0 @@
---
layout: docs
page_title: KMS worker configuration
description: |-
KMS worker-specific parameters.
---
# KMS worker configuration
This page describes configuration for workers that authenticate to upstreams
using a shared KMS. 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 reauthenticates using the trusted KMS.
~> If using 0.13+ workers with pre-0.13 controllers you _must_ set the
`use_deprecated_kms_auth_method` value to true. Additionally, a worker
registered using this method _against a pre-0.13 controller_ will only be able
to register directly to a controller, and cannot be used as part of multi-hop or
Vault private access capabilities.
KMS Workers require a `name` field. This specifies a unique name of this worker
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.
KMS Workers 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.
```hcl
worker {
name = "example-worker"
description = "An example worker"
public_addr = "5.1.23.198"
# Uncomment if using 0.13 worker against pre-0.13 controller
# use_deprecated_kms_auth_method = true
}
```
KMS Workers 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
kms "aead" {
purpose = "worker-auth"
aead_type = "aes-gcm"
key = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
key_id = "global_worker-auth"
}
```
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.) 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
kms "aead" {
purpose = "downstream-worker-auth"
aead_type = "aes-gcm"
key = "XthZVtFtBD1Bw1XwAWhZKVrIwRhR7HcZ"
key_id = "iot-nodes-auth"
}
kms "aead" {
purpose = "downstream-worker-auth"
aead_type = "aes-gcm"
key = "OLFhJNbEb3umRjdhY15QKNEmNXokY1Iq"
key_id = "production-nodes-auth"
}
```
In the examples above we are encoding key bytes directly in the configuration
file. This is because we are using the `aead` method where you directly supply a
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,
see our [KMS documentation](/boundary/docs/configuration/kms).
## Complete configuration example
```hcl
listener "tcp" {
purpose = "proxy"
tls_disable = true
address = "127.0.0.1"
}
worker {
# Name attr must be unique across workers
name = "demo-worker-1"
description = "A default worker created for demonstration"
# Workers must be able 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"]
}
# use_deprecated_kms_auth_method = true
}
# must be same key as used on controller config
kms "aead" {
purpose = "worker-auth"
aead_type = "aes-gcm"
key = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
key_id = "global_worker-auth"
}
```
[`initial_upstreams`](/boundary/docs/configuration/worker/overview#initial_upstreams)
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 the [Worker
Tags](/boundary/docs/concepts/filtering/worker-tags) page.
website/content/docs/configuration/worker/pki-worker.mdx
-101
View File
@@ -1,101 +0,0 @@
---
layout: docs
page_title: PKI worker configuration
description: |-
PKI worker-specific parameters.
---
# PKI worker configuration
PKI Workers authenticate to Boundary using an activation token. They require an
accessible directory defined by `auth_storage_path` for credential storage and
rotation.
Example (not safe for production!):
```hcl
worker {
auth_storage_path="/var/lib/boundary"
initial_upstreams = ["10.0.0.1"]
}
```
## Authorization methods
There are two mechanisms that can be used to register a PKI 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="/var/lib/boundary"
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 reads this token and uses 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 = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
key_id = "worker-auth-storage"
}
```
## Session recording
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
[Session recording](/boundary/docs/configuration/session-recording) requires at least one PKI worker with access to local and remote storage.
PKI workers used for session recording require an accessible directory defined by `recording_storage_path` for
storing in-progress session recordings. On session closure, a local session recording is moved to remote storage and
deleted locally.
Development example:
```hcl
worker {
auth_storage_path="/var/lib/boundary"
initial_upstreams = ["10.0.0.1"]
recording_storage_path="/local/storage/directory"
}
```
~> **Note:** `name` and `description` fields are not valid config fields for PKI
workers. These fields are only valid for [KMS Workers](/boundary/docs/configuration/worker/kms-worker). `name` and
`description` can only be set for PKI workers through the API.
website/content/docs/configuration/worker/worker-configuration.mdx
+213
View File
@@ -0,0 +1,213 @@
---
layout: docs
page_title: Worker configuration
description: |-
Worker-specific parameters.
---
# Worker configuration
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.
Example (not safe for production!):
```hcl
worker {
auth_storage_path="/var/lib/boundary"
initial_upstreams = ["10.0.0.1"]
}
```
## 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.
### 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="/var/lib/boundary"
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 reads this token and uses 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. 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
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-led authorization & authentication flow
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.
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`
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.
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.
```hcl
worker {
name = "example-worker"
description = "An example worker"
public_addr = "5.1.23.198"
}
```
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
kms "aead" {
purpose = "worker-auth"
aead_type = "aes-gcm"
key = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
key_id = "global_worker-auth"
}
```
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
across various networks, each with their own separate KMS system or key:
```hcl
kms "aead" {
purpose = "downstream-worker-auth"
aead_type = "aes-gcm"
key = "XthZVtFtBD1Bw1XwAWhZKVrIwRhR7HcZ"
key_id = "iot-nodes-auth"
}
kms "aead" {
purpose = "downstream-worker-auth"
aead_type = "aes-gcm"
key = "OLFhJNbEb3umRjdhY15QKNEmNXokY1Iq"
key_id = "production-nodes-auth"
}
```
In the examples above we are encoding key bytes directly in the configuration
file. This is because we are using the `aead` method where you directly supply a
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,
see our [KMS documentation](/boundary/docs/configuration/kms).
## Complete configuration example
```hcl
listener "tcp" {
purpose = "proxy"
tls_disable = true
address = "127.0.0.1"
}
worker {
# Name attr must be unique across workers
name = "demo-worker-1"
description = "A default worker created for demonstration"
# Workers must be able 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"]
}
}
# must be same key as used on controller config
kms "aead" {
purpose = "worker-auth"
aead_type = "aes-gcm"
key = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
key_id = "global_worker-auth"
}
```
[`initial_upstreams`](/boundary/docs/configuration/worker/overview#initial_upstreams)
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 the [Worker
Tags](/boundary/docs/concepts/filtering/worker-tags) page.
## 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"
}
```
## Session recording
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
[Session recording](/boundary/docs/configuration/session-recording) requires at least one Worker with access to local and remote storage.
Workers used for session recording require an accessible directory defined by `recording_storage_path` for storing in-progress session recordings. On session closure, a local session recording is moved to remote storage and deleted locally.
Development example:
```hcl
worker {
auth_storage_path="/var/lib/boundary"
initial_upstreams = ["10.0.0.1"]
recording_storage_path="/local/storage/directory"
}
```
~> **Note:** `name` and `description` fields are not valid config fields for
Workers using activation tokens(Worker-led & Controller-led authorization), and can only be set through the API. These config fields are only valid for [Workers using the KMS authorization method](/boundary/docs/configuration/worker/worker).
website/content/docs/install-boundary/configure-workers.mdx
+9 -11
View File
@@ -46,9 +46,8 @@ In the example above, the proper IAM roles and permissions for the given `AWS_AC
## Prepare the worker KMS keys
The worker-auth storage KMS key is used by a PKI worker for the encrypted storage of authentication keys.
This is not recommended for PKI workers.
If it is not specified, the authentication keys are not encrypted on disk.
The worker-auth storage KMS key is used by a Worker for the encrypted storage of authentication keys.
This is recommended Workers using controller-led or worker-led methods. If it is not specified, the authentication keys are not encrypted on disk.
Optionally, if you deploy KMS authentication-driven Boundary workers, an additional KMS key must be generated to authenticate the Boundary worker with the controller.
HashiCorp strongly recommends using the Key Management Ssytem (KMS) of the cloud provider where you deploy your Boundary workers.
@@ -59,8 +58,8 @@ Refer to your cloud provider's documentation, for more information.
After you create the requisite key or keys in the cloud provider of your choice, you can begin configuring the workers.
The following configuration examples all employ the PKI method of authentication with a worker-led authorization flow.
For more information on configuring KMS authentication for Boundary workers, refer to the [KMS worker configuration documenation](/boundary/docs/configuration/worker/kms-worker).
The following configuration examples all employ the worker-led authorization flow.
For more information on configuring KMS authentication for Boundary workers, refer to the [KMS authentication configuration documenation](/boundary/docs/configuration/worker/worker-configuration).
If you use Boundary Enterprise, you can configure multiple workers to act in three different roles: ingress, intermediary, and egress.
For Community Edition, workers only serve one role, acting as both the point of ingress and egress.
@@ -446,9 +445,9 @@ Run the following commands to start the service:
1. `sudo systemctl enable boundary`
1. `sudo systemctl start boundary`
## Adopt the PKI workers (optional)
## Adopt the Workers (optional)
If you use the PKI workers as outlined above, you must adopt the Boundary PKI workers.
If you use the Workers as outlined above, you must adopt the Boundary Workers.
Complete the following steps to adopt the workers:
<Tabs>
@@ -460,18 +459,17 @@ Complete the following steps to adopt the worker using the UI:
1. Log in to Boundary as the admin user.
1. Select **Workers** in the navigation pane.
Note that only KMS workers are listed.
1. Click **New**.
1. (Optional) You can use the new PKI workers page to construct the contents of the `pki-worker.hcl` file, if you did not [create the configuration file](/boundary/docs/install-boundary/configure-workers#create-the-worker-configurations) as part of the installation process above.
1. (Optional) You can use the workers page to construct the contents of the `worker.hcl` file, if you did not [create the configuration file](/boundary/docs/install-boundary/configure-workers#create-the-worker-configurations) as part of the installation process above.
Provide the following details, and Boundary constructs the worker configuration file for you:
- Boundary Cluster ID
- Worker Public Address
- Config file path
- Worker Tags
1. Scroll to the bottom of the **New PKI Worker** page, and paste the **Worker Auth Registration Request** key.
1. Scroll to the bottom of the **New Worker** page, and paste the **Worker Auth Registration Request** key.
Boundary provides you with the **Worker Auth Registration Request** key in the CLI output when you start the worker.
You can also locate this value in the `auth_request_token` file.
@@ -533,7 +531,7 @@ name, and admin password when prompted.
You can also locate this value in the `auth_request_token` file.
The token is used to issue a create worker request that will authorize the worker to Boundary and make it available.
Currently worker creation is only supported for PKI workers with an authorization token.
Currently worker creation is only supported for Workers with an authorization token(worker-led and controller-led).
</Tab>
</Tabs>
website/data/docs-nav-data.json
+2 -6
View File
@@ -375,12 +375,8 @@
"path": "configuration/worker"
},
{
"title": "PKI workers",
"path": "configuration/worker/pki-worker"
},
{
"title": "KMS workers",
"path": "configuration/worker/kms-worker"
"title": "Configuration",
"path": "configuration/worker/worker-configuration"
}
]
},
website/redirects.js
+8
View File
@@ -154,4 +154,12 @@ module.exports = [
destination: '/boundary/docs/concepts/host-discovery',
permanent: true,
},
{
source: '/boundary/docs/configuration/worker/kms-worker',
destination: '/boundary/docs/configuration/worker/worker-configuration',
},
{
source: '/boundary/docs/configuration/worker/pki-worker',
destination: '/boundary/docs/configuration/worker/worker-configuration'
},
]