docs: Update main branch with 0.12.0 revisions (#2975)

* docs: Add HCP only to heading * docs: Add worker requirements * docs: Fix heading format and hierarchy * docs: Fix headings format * docs: Update feature name using "sessions" * docs: Fix heading hierarchy * docs: Fix headings format * docs: Fix spacing in title
2023-02-16 13:37:25 -05:00
1 parent 7e87f0f0a1
commit d7049e4e79
@@ -30,7 +30,7 @@ The default value is `GET`.
 - `http_request_body` - (optional) The body of the HTTP request the library sends to Vault when requesting credentials.
 Only valid if `http_method` is set to `POST`.

-### Vault SSH certificate credential library attributes
+### Vault SSH certificate credential library attributes<sup>HCP Only</sup>

 As of Boundary 0.12.0, you can configure SSH credential injection using [Vault's SSH secrets engine](/vault/docs/secrets/ssh) to create the SSH certificate credentials.
 SSH certificate-based authentication extends key-based authentication using digital signatures.
@@ -40,7 +40,7 @@ A target has the following configurable attributes:
  Represents a network resource address and is used when establishing a session.
  Accepts no port, only an IP address or DNS name.

-### TCP Target Attributes
+### TCP target attributes

 TCP targets have the following additional attributes:

@@ -79,7 +79,7 @@ TCP targets have the following additional attributes:
  The default is 8 hours (28800 seconds).
  This value must be greater than 0.

-### SSH Target Attributes <sup>HCP Only</sup>
+### SSH target attributes <sup>HCP Only</sup>

 SSH targets can source username/password or SSH private key credentials from Vault [credential libraries][] or static
 [credentials][]. Boundary then injects credentials into the SSH session between a client and end host. This allows users to
@@ -122,7 +122,7 @@ SSH targets have the following additional attributes:
  The default is 8 hours (28800 seconds).
  This value must be greater than 0.

-## Referenced By
+## Referenced by

 - [Credential Library][]
 - [Host Set][]
@@ -154,7 +154,7 @@ SSH targets have the following additional attributes:
 [user]: /boundary/docs/concepts/domain-model/users
 [users]: /boundary/docs/concepts/domain-model/users

-## Service API Docs
+## Service API docs

 The following services are relevant to this resource:

@@ -100,7 +100,7 @@ array with the tags intended for the particular key is required:
 ["prod", "webservers"]
 ```

-# Worker Filtering
+# Worker filtering

 As filters operate on JSON Pointer selectors, the values that are input into the
 filter come from the JSON representation of the values in the configuration file
@@ -134,7 +134,7 @@ Following are some examples of using these values in filters:

 - Grouping: `("us-east-1" in "/tags/region" and "/name" == "web-prod-us-east-1") or "webservers" in "/tags/type"`

-# Target Worker Filtering
+# Target worker filtering

 Once workers have tags, you can use these tags to control which
 workers are allowed to manage a given session by specifying optional worker filter attributes
@@ -147,7 +147,7 @@ The `ingress_worker_filter`<sup>HCP Only</sup> attribute controls which workers
 This is the worker a client connects to when initiating a connection to a target.


-# Vault Worker Filtering <sup>HCP Only</sup>
+# Vault worker filtering <sup>HCP only</sup>
 Tags are used to control which [PKI workers] can manage Vault requests by specifying
 a `worker_filter`attribute when configuring [credential stores].

@@ -6,7 +6,7 @@ description: |-
 ---


-## PKI Worker Configuration
+# PKI Worker Configuration
 PKI Workers authenticate to Boundary using a certificate-based method, allowing
 for worker deployment without using a shared KMS.

@@ -22,10 +22,10 @@ worker {
 }
 ```

-## Authorization Methods
+## Authorization methods
 There are two mechanisms that can be used to register a worker to the cluster.

-### Controller-Led Authorization Flow
+### 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
@@ -53,7 +53,7 @@ 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
+### 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
@@ -61,7 +61,7 @@ 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
+## 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!):
@@ -78,16 +78,16 @@ kms "aead" {
 workers. These fields are only valid for [KMS Workers][]. `name` and
 `description` can only be set for PKI workers through the API.

-# Multi-Hop Workers<sup>HCP Only</sup>
+## Multi-hop sessions <sup>HCP only</sup>

 You can use the `hcp_boundary_cluster_id` field to configure PKI workers to connect to your HCP
 Boundary cluster or the `initial_upstreams` field to connect directly to other workers,
 when set to that worker's `public_addr` field.

-A multi-hop configuration is when two or more workers are connected, and there are multiple “hops” from a worker to
-the controller. There are no limits on the amount of workers allowed in a multi-hop configuration.
+A multi-hop session is when two or more workers are connected, and there are multiple “hops” from a worker to
+the controller. There are no limits on the amount of workers allowed in a multi-hop session configuration.

-The multi-hop configuration introduces the concepts of “upstream” and “downstream” workers. If you view controllers
+The multi-hop session introduces the concepts of “upstream” and “downstream” workers. If you view controllers
 as the “top” of a multi-hop chain, downstream workers reside below a worker in the chain, while upstream workers reside
 above a worker in the chain. For example, in the diagram below, Worker 2’s upstream is Worker 1, and its
 downstream is Worker 3.
@@ -102,7 +102,31 @@ ingress and egress for session traffic to a [target][]. Ingress worker filters d
 workers you connect with to initiate a session, and egress worker filters determine which workers are
 used to access targets.

-# Complete Configuration Example
+### Multi-hop worker requirements
+
+When you configure multi-hop sessions, there is an "ingress" worker, an "egress" worker, and any number of intermediary workers.
+Ingress, egress, and intermediary workers have the following requirements.
+
+#### Ingress worker requirements
+
+To proxy target connections, ingress workers require outbound access to the Boundary control plane and inbound access from clients.
+
+#### Intermediary worker requirements
+
+Intermediary workers require outbound access to an upstream worker.
+The upstream worker may be an ingress worker or another intermediary worker.
+Any upstream intermediary worker needs eventual connectivity to an ingress worker via trusted intermediaries.
+
+Intermediary workers also require inbound access from a downstream worker.
+The downstream worker may be an egress worker or another intermediary worker.
+Any downstream intermediary worker needs eventual connectivity to an egress worker via trusted intermediaries.
+
+#### Egress worker requirements
+
+To proxy target connections, egress workers require outbound access to an upstream worker and outbound access to the destination host.
+Inbound session connections from clients reach the egress worker via reverse proxy; the ingress worker is initiated from the egress worker.
+
+## Complete configuration example

 ```hcl
 listener "tcp" {