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>
3 years ago · 5b9369e8a5
parent 17c0774bce
commit 5b9369e8a5
2 changed files with 138 additions and 3 deletions
--- a/website/content/docs/install-boundary/configure-controllers.mdx
+++ b/website/content/docs/install-boundary/configure-controllers.mdx
@ -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.
--- a/website/content/docs/install-boundary/configure-workers.mdx
+++ b/website/content/docs/install-boundary/configure-workers.mdx
@ -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`.