From d7049e4e79c3d70621d4ed5b4f0d330690884ac9 Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Thu, 16 Feb 2023 13:37:25 -0500 Subject: [PATCH] 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 --- .../domain-model/credential-libraries.mdx | 2 +- .../docs/concepts/domain-model/targets.mdx | 8 ++-- .../docs/concepts/filtering/worker-tags.mdx | 6 +-- .../docs/configuration/worker/pki-worker.mdx | 44 ++++++++++++++----- 4 files changed, 42 insertions(+), 18 deletions(-) diff --git a/website/content/docs/concepts/domain-model/credential-libraries.mdx b/website/content/docs/concepts/domain-model/credential-libraries.mdx index d91cc171d2..6f09ce5733 100644 --- a/website/content/docs/concepts/domain-model/credential-libraries.mdx +++ b/website/content/docs/concepts/domain-model/credential-libraries.mdx @@ -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 attributesHCP Only 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. diff --git a/website/content/docs/concepts/domain-model/targets.mdx b/website/content/docs/concepts/domain-model/targets.mdx index a1a4e3e06b..93eba552cc 100644 --- a/website/content/docs/concepts/domain-model/targets.mdx +++ b/website/content/docs/concepts/domain-model/targets.mdx @@ -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 HCP Only +### SSH target attributes HCP Only 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: diff --git a/website/content/docs/concepts/filtering/worker-tags.mdx b/website/content/docs/concepts/filtering/worker-tags.mdx index 7e277f631e..1608d9d246 100644 --- a/website/content/docs/concepts/filtering/worker-tags.mdx +++ b/website/content/docs/concepts/filtering/worker-tags.mdx @@ -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`HCP Only attribute controls which workers This is the worker a client connects to when initiating a connection to a target. -# Vault Worker Filtering HCP Only +# Vault worker filtering HCP only Tags are used to control which [PKI workers] can manage Vault requests by specifying a `worker_filter`attribute when configuring [credential stores]. diff --git a/website/content/docs/configuration/worker/pki-worker.mdx b/website/content/docs/configuration/worker/pki-worker.mdx index 6e5af467de..9e6c43cd85 100644 --- a/website/content/docs/configuration/worker/pki-worker.mdx +++ b/website/content/docs/configuration/worker/pki-worker.mdx @@ -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 WorkersHCP Only +## Multi-hop sessions HCP only 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" {