docs: Update worker config with tabs (#3614)
* docs: Update worker config with tabs * docs: Apply batch of suggestions from code review Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com> * docs: Fix spacing in Note * docs: Note appears in 2 places --------- Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
This commit is contained in:
Dan HeathandRobin Beck authored and 
GitHub committed
1 parent
17c0774bce
commit
5b9369e8a5
2 files changed
+138
-3
No files matched your search
@@ -110,7 +110,9 @@ AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
||||
</CodeBlockConfig>
|
||||
|
||||
<Note>
|
||||
|
||||
In the example above, the proper IAM roles and permissions for the given `AWS_ACCESS_KEY` and `AWS_SECRET_ACCESS_KEY` must be in place so that Boundary can use them to access the different KMS keys.
|
||||
|
||||
</Note>
|
||||
|
||||
Next, populate the `controller.hcl` file with any relevant configuration information.
|
||||
|
||||
@@ -7,8 +7,6 @@ description: |-
|
||||
|
||||
# Configure workers
|
||||
|
||||
In this topic, we present an opinionated deployment model to show Boundary Enterprise features such as multi-hop sessions.
|
||||
|
||||
Before you configure workers, you should have completed the following steps:
|
||||
|
||||
- Installed Boundary on at least three [controller nodes](/boundary/docs/install-boundary/configure-controllers).
|
||||
@@ -20,7 +18,7 @@ Before you configure workers, you should have completed the following steps:
|
||||
|
||||
In the following configuration files, there are common configuration components as well as some unique components depending on the role the Boundary worker performs.
|
||||
There are three files, one for each worker in a unique network boundary.
|
||||
In a multi-hop configuration, the Boundary workers can serve one of three purposes: an ingress worker, an ingress/egress worker, or an egress worker.
|
||||
Additionally, Boundary Enterprise supports a [multi-hop configuration](/boundary/docs/configuration/worker#multi-hop-worker-capabilities-hcp-ent) in which the Boundary workers can serve one of three purposes: an ingress worker, an ingress/egress worker, or an egress worker.
|
||||
|
||||
## Prepare the environment files
|
||||
|
||||
@@ -41,7 +39,9 @@ AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
||||
</CodeBlockConfig>
|
||||
|
||||
<Note>
|
||||
|
||||
In the example above, the proper IAM roles and permissions for the given `AWS_ACCESS_KEY` and `AWS_SECRET_ACCESS_KEY` must be in place so that Boundary can use them to access the different KMS keys.
|
||||
|
||||
</Note>
|
||||
|
||||
## Prepare the worker KMS keys
|
||||
@@ -62,6 +62,21 @@ After you create the requisite key or keys in the cloud provider of your choice,
|
||||
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).
|
||||
|
||||
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.
|
||||
Select your Boundary edition, and complete the following steps to configure workers.
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="Enterprise">
|
||||
|
||||
For Boundary Enterprise, you can configure ingress, intermediary, and egress workers to take advantage of [multi-hop worker capabilities](/boundary/docs/configuration/worker#multi-hop-worker-capabilities-hcp-ent).
|
||||
|
||||
Note that "ingress," "intermediary," and "egress" are general ways to describe how the respective worker interacts with resources.
|
||||
A worker can serve more than one of those roles at a time.
|
||||
Refer to [Multi-hop sessions](/boundary/docs/concepts/workers#multi-hop-sessions-hcp-ent) for more information.
|
||||
|
||||
Complete the steps below to configure workers for Boundary Enterprise.
|
||||
|
||||
### Ingress worker configuration
|
||||
|
||||
Create the `ingress-worker.hcl` file with the relevant configuration information:
|
||||
@@ -305,6 +320,124 @@ If present, `boundary server` starts a worker subprocess.
|
||||
|
||||
Refer to the documentation for additional [top-level configuration options](/boundary/docs/configuration) and additional [controller-specific options](/boundary/docs/configuration/controller).
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Community Edition">
|
||||
|
||||
For the Community Edition of Boundary, you must configure a worker server that communicates with the controller and is responsible for storage-related tasks.
|
||||
|
||||
Boundary Community Edition only supports egress workers. To configure workers for multi-hop sessions, check the Boundary Enterprise configuration.
|
||||
|
||||
Complete the following steps to configure the worker.
|
||||
|
||||
### Worker configuration
|
||||
|
||||
Create the `egress-worker.hcl` file with the relevant configuration information:
|
||||
|
||||
<CodeBlockConfig lineNumbers filename="/etc/boundary.d/egress-worker.hcl">
|
||||
|
||||
```hcl
|
||||
# disable memory from being swapped to disk
|
||||
disable_mlock = true
|
||||
|
||||
# listener denoting this is a worker proxy
|
||||
listener "tcp" {
|
||||
address = "0.0.0.0:9202"
|
||||
purpose = "proxy"
|
||||
}
|
||||
|
||||
# worker block for configuring the specifics of the
|
||||
# worker service
|
||||
worker {
|
||||
public_addr = "<worker_public_addr>"
|
||||
initial_upstreams = ["<controller_lb_address>:9201"]
|
||||
auth_storage_path = "/etc/boundary.d/auth_storage/"
|
||||
tags {
|
||||
type = ["worker", "egress"]
|
||||
}
|
||||
}
|
||||
|
||||
# Events (logging) configuration. This
|
||||
# configures logging for ALL events to both
|
||||
# stderr and a file at /var/log/boundary/<boundary_use>.log
|
||||
events {
|
||||
audit_enabled = true
|
||||
sysevents_enabled = true
|
||||
observations_enable = true
|
||||
sink "stderr" {
|
||||
name = "all-events"
|
||||
description = "All events sent to stderr"
|
||||
event_types = ["*"]
|
||||
format = "cloudevents-json"
|
||||
}
|
||||
sink {
|
||||
name = "file-sink"
|
||||
description = "All events sent to a file"
|
||||
event_types = ["*"]
|
||||
format = "cloudevents-json"
|
||||
file {
|
||||
path = "/var/log/boundary"
|
||||
file_name = "egress-worker.log"
|
||||
}
|
||||
audit_config {
|
||||
audit_filter_overrides {
|
||||
sensitive = "redact"
|
||||
secret = "redact"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# kms block for encrypting the authentication PKI material
|
||||
kms "awskms" {
|
||||
purpose = "worker-auth-storage"
|
||||
region = "us-east-1"
|
||||
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey5"
|
||||
endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
|
||||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
Refer to the list below for explanations of the parameters used in the example above:
|
||||
|
||||
- `disable mlock (bool: false)` - Disables the server from executing the `mlock` syscall, which prevents memory from being swapped to the disk.
|
||||
This is fine for local development and testing.
|
||||
However, it is not recommended for production unless the systems running Boundary use only encrypted swap or do not use swap at all.
|
||||
Boundary only supports memory locking on UNIX-like systems that support `mlock()` syscall like Linux and FreeBSD.
|
||||
|
||||
On Linux, to give the Boundary executable the ability to use `mlock` syscall without running the process as root, run the following command:
|
||||
|
||||
`sudo setcap cap_ipc_lock=+ep $(readlink -f $(which boundary))`
|
||||
|
||||
If you use a Linux distribution with a modern version of systemd, you can add the following directive to the **"[Service]"** configuration section:
|
||||
|
||||
`LimitMEMLOCK=infinity`
|
||||
|
||||
- `listener` - Configures the listeners on which Boundary serves traffic (API cluster and proxy).
|
||||
- `worker` - Configures the worker.
|
||||
If present, `boundary server` starts a worker subprocess.
|
||||
- `events` - Configures event-specific parameters.
|
||||
|
||||
The example events configuration above is exhaustive and writes all events to both `stderr` and a file.
|
||||
This configuration may or may not work for your organization's logging solution.
|
||||
|
||||
- `kms` - Configures KMS blocks for [various purposes](/boundary/docs/concepts/security/data-encryption).
|
||||
|
||||
Refer to the links below for configuration information for the different cloud KMS blocks:
|
||||
|
||||
- [AWS](/boundary/docs/configuration/kms/awskms)
|
||||
- [Azure](/boundary/docs/configuration/kms/azurekeyvault)
|
||||
- [GCP](/boundary/docs/configuration/kms/gcpckms)
|
||||
- [OCI](/boundary/docs/configuration/kms/ocikms)
|
||||
- [AliCloud](/boundary/docs/configuration/kms/alicloudkms)
|
||||
- [Vault Transit](/boundary/docs/configuration/kms/transit)
|
||||
|
||||
Refer to the documentation for additional [top-level configuration options](/boundary/docs/configuration) and additional [controller-specific options](/boundary/docs/configuration/controller).
|
||||
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Start the Boundary service
|
||||
|
||||
When the configuration files are in place on each Boundary controller, you can proceed to enable and start the binary on each of the Boundary worker nodes using `systemd`.
|
||||
|
||||
Reference in new issue
Block a user