Dheath 0.18.0 assembly (#5175)

* docs: TS public beta docs * docs: Updates * docs: Move Client Agent sections * docs: Updates * docs: Fix typo * docs: Remove x86 * docs: Add lead in sentence for links * docs: FAQ updates * docs: Edits and file name fixes * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Irena Rindos <irenarindos@users.noreply.github.com> * docs: Add alias refresh interval * docs: Remove recurse only option * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * docs: Updates from code review * docs: Update support request * docs: Fix a typo * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> * docs: Delete log example, create tabs * client-agent: rework configuration docs The section in the configuration talking about reloading the config was repetitive and verbose. Combine the different sections into two separate sections, one for updating general values and one for reloading values, on MacOS only. This also removes the specific Log section. * docs: Minor rewrites * client-agent: consistently use $ for shell sessions * aliases: discourage single-word aliases The use of single-word aliases breaks Transparent Sessions on Windows, so we should discourage it. See ICU-15255 for more information. * transparent-sessions: add known issues Add two new known issues. * client-agent: add troubleshooting section * transparent-sessions: emphasize troubleshooting guide * correct links I haven't actually validated these links, but they are now consistent with the rest of the links. * Review comments * client-agent: clarify that not all sessions are listed by command * transparent-session: add known issue regarding Windows installer * docs: Minor rewrites * docs: Fix a typo * docs: Add AssumeRole support * docs: Add Backblaze support * docs: Minor revision * docs: Update MinIO reqs * docs: Add supported Hitachi version * docs: Trigger a new build * docs: Clarify Desktop compatibility with control plane * Update website/content/docs/enterprise/supported-versions.mdx Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com> * docs: Release notes 0.18.0 * docs: Add link to Client Agent docs * docs: Update ts definition * docs: Remove stray line * docs: Fix minor issues with the assembly branch * docs: Move section * docs: Add section * docs: Remove duplicate section --------- Co-authored-by: Irena Rindos <irenarindos@users.noreply.github.com> Co-authored-by: Johan Brandhorst-Satzkorn <johan.brandhorst@gmail.com> Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
hashicorp · Oct 15, 2024 · 3e78e3c · 3e78e3c
1 parent 0797f81
commit 3e78e3c
Show file tree

Hide file tree

Showing 12 changed files with 1,001 additions and 9 deletions.
diff --git a/website/content/docs/api-clients/client-agent.mdx b/website/content/docs/api-clients/client-agent.mdx
diff --git a/website/content/docs/concepts/aliases.mdx b/website/content/docs/concepts/aliases.mdx
@@ -38,7 +38,29 @@ You can configure Boundary to allow a select few users to manage those targets,
 
 An alias is a globally unique, DNS-like string that is associated with a destination resource. The alias `value` parameter does not have to be delimited by a suffix, and can be just a hostname.
 
-Examples of valid aliases include `webserver` and `webserver.boundary`.
+Examples of valid aliases include `database.boundary` and `webserver.boundary`.
+
+### Single word aliases and transparent sessions
+
+HashiCorp recommends that you do not use single-word aliases such as `webserver` as opposed to `webserver.boundary`, because single-word aliases do not work intuitively on Windows.
+Windows DNS resolution does not support resolving unqualified single word DNS hostnames.
+You can make the hostname fully qualified, but is not intuitive to most users.
+
+For example the following hostname works:
+
+```
+ssh mytarget.
+```
+
+But this hostname does not work:
+
+```
+ssh mytarget
+```
+
+For this reason, if you expect any Windows users to use an alias, it contains a dot (`.`) anywhere in the value.
+
+See the [transparent sessions](/boundary/docs/concepts/transparent-sessions) documentation for more information.
 
 ## Scopes
 
@@ -260,4 +282,4 @@ Complete the following steps to add an alias to a target:
    - `-authorize-session-host-id=<string>` - Optionally indicates the host ID to use when you use the alias to authorize a session.
 
 </Tab>
-</Tabs>
+</Tabs>
diff --git a/website/content/docs/concepts/connection-workflows/index.mdx b/website/content/docs/concepts/connection-workflows/index.mdx
@@ -17,6 +17,18 @@ Refer to the [`boundary connect`](/boundary/docs/commands/connect) documentation
 
 To practice using the `boundary connect` command in a development environment, refer to the **Connect to your first target** tutorial for either [HCP Boundary](/boundary/tutorials/hcp-getting-started/hcp-getting-started-connect) or the [self-managed versions](/boundary/tutorials/oss-getting-started/oss-getting-started-connect) of Boundary.
 
+## Transparent sessions
+
+@include 'alerts/enterprise-only.mdx'
+
+@include 'alerts/beta.mdx'
+
+Transparent sessions shift Boundary from an active connection model to a passive connection model.
+Instead of interacting with the Boundary CLI or Desktop client and having to remember specific IDs or ephemeral ports to connect to targets, Boundary operates in the background.
+If a user is authenticated and authorized, Boundary intercepts DNS calls and routes traffic through a session automatically.
+
+Refer to the [transparent sessions](/boundary/docs/concepts/transparent-sessions) documentation for more information.
+
 ## Connect helpers
 
 Boundary features connect helpers that assist with making connections to targets using certain protocols.
@@ -52,7 +64,7 @@ Refer to the [SSH ProxyCommand](/boundary/docs/concepts/connection-workflows/wor
 
 ## Multi-hop sessions
 
-<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
+@include 'alerts/enterprise-only.mdx'
 
 Most organizations want to provide access to infrastructure without exposing private networks.
 Many organizations also have complex network topologies requiring inbound traffic to route through multiple network enclaves to reach the target system.

diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx
@@ -9,7 +9,7 @@ Boundary uses dynamic host catalogs to automatically discover AWS EC2 instances
 
 ## Create a host catalog to connect with AWS
 Boundary uses plugins to integrate with a variety of providers. To use
-a dynamic host catalog to integrate with AWS, you create a host catalog of the `plugin` type 
+a dynamic host catalog to integrate with AWS, you create a host catalog of the `plugin` type
 and set the `plugin-name` value to `aws`. You must also provide the specific
 fields needed for Boundary to authenticate with AWS.
 
@@ -57,6 +57,10 @@ The fields following the `attr` and `secret` flags are specific to AWS and are r
 - `disable_credential_rotation`: When set to `true`, Boundary will not rotate the credentials with AWS automatically.
 - `region`: The region to configure the host catalog for. All host sets in this
   catalog will be configured for this region.
+- `role_arn`: The AWS role ARN used for `AssumeRole` authentication. If you provide a `role_arn` value, you must also set `disable_credential_rotation` to `true`.
+- `role_external_id`: The external ID that you configured for the `AssumeRole` provider.
+- `role_session_name`: The session name that you configured for the `AssumeRole` provider.
+- `role_tags`: The key-value pair tags that you configured for the `AssumeRole` provider.
 - `access_key_id`: The access key ID for the IAM user to use with this host
   catalog.
 - `secret_access_key`: The secret access key for the IAM user to use with this

diff --git a/website/content/docs/concepts/transparent-sessions.mdx b/website/content/docs/concepts/transparent-sessions.mdx
@@ -0,0 +1,97 @@
+---
+layout: docs
+page_title: Transparent sessions
+description: |-
+  Learn how transparent sessions enable you to connect to Boundary resources without remembering resource IDs or port numbers.
+---
+
+# Transparent sessions
+
+@include 'alerts/enterprise-only.mdx'
+
+@include 'alerts/beta.mdx'
+
+Transparent sessions shift Boundary from an active connection model to a passive connection model.
+Boundary operates in the background instead of requiring you to remember specific resource IDs or ephemeral ports to connect to targets.
+As long as Boundary authenticates a user and the user is authorized to access the target, Boundary intercepts the DNS call and routes traffic through a session automatically.
+
+Transparent sessions require [aliases](/boundary/docs/concepts/aliases) and the [Boundary Client Agent](/boundary/docs/api-clients/client-agent).
+
+The Boundary Desktop client facilitates quick target discovery and session establishment using your preferred client.
+If you configure aliases for your targets, install the Boundary Client Agent, and ensure you are authenticated to the cluster, connections are transparent to the user.
+Boundary provides OS notifications to make it clear when you connect to a target using a transparent session.
+
+Boundary supports Windows and MacOS for the transparent sessions public beta.
+
+## Requirements
+
+Before you configure transparent sessions, you must:
+
+- Ensure that the Boundary CLI and Boundary Desktop are not installed in the environment in which you want to run the transparent sessions beta.
+- Download the appropriate installer for your Windows or MacOS environment from the [downloads](/boundary/install) page.
+
+## Install clients
+
+Complete the following steps to install the Boundary Client Agent, CLI, and Desktop client:
+
+1. Install Boundary using the installer.
+Make sure to select the options **Boundary Client Agent**, **CLI**, and **Desktop**.
+1. Open the CLI and type the following command to confirm that the version is 0.18.0:
+   ```shell-session
+   $ boundary version
+   ```
+1. In the CLI, run the status command to confirm that the Boundary Client Agent has started:
+
+   ```shell-session
+   $ boundary client-agent status
+   ```
+
+## Configure targets
+
+The following section details how to configure targets and test the transparent sessions public beta feature.
+
+If you use a cluster that was created earlier than release 0.16.0, you must add the grant `list-resolvable-aliases` so that the client agent can populate the local alias cache.
+As an example, you could add the grant `type=user;actions=list-resolvable-aliases;ids=*`.
+
+Complete the following steps to configure targets and test transparent sessions:
+
+1. Authenticate to Boundary using the CLI or Desktop client.
+1. [Create a new target with an alias](/boundary/docs/concepts/aliases#create-an-alias-during-target-creation) or [create an alias for an existing target](/boundary/docs/concepts/aliases#create-an-alias-for-an-existing-target).
+Ensure that you have authorization to establish a session to the target.
+1. Open the client of your choice and [connect to your target using the alias](/boundary/docs/concepts/aliases#connect-to-a-target-using-an-alias).
+
+   Boundary routes your session using the Boundary Client Agent.
+   You can validate that Boundary routed the session by looking at the **Sessions** page in the Desktop client, by typing `boundary sessions list -recursive` in the CLI, or by looking at sessions managed by the Client Agent using `boundary client-agent sessions`.
+
+   <Note>
+
+   The Client Agent periodically requests an updated list of aliases from the controller, so the alias may not work immediately after you create it.
+   It should not take longer than 2 minutes for the alias to be updated in the Client Agent. If you still see connection issues after 2 minutes,
+   follow the troubleshooting steps in [the Client Agent troubleshooting guide](/boundary/docs/api-clients/client-agent#troubleshooting).
+
+   </Note>
+
+When you have validated that transparent sessions work, you can create and establish transparent sessions to other services.
+Make a list of the services you use, add these resources to Boundary as targets, and create workers as needed for network partitions.
+
+## Known issues
+
+Refer to the following table for known issues that may affect the public beta:
+
+| Issue | Description |
+| ----- | ----------- |
+| Connection is reset when trying to reconnect | If you use an SSH transparent session and then cancel the connection, you may have trouble reconnecting until Boundary cleans up the session. |
+| SSH connection fails with man-in-the-middle warning | On Ubuntu systems, the initial transparent session may be successful, but any subsequent connections prompt a warning that you may be experiencing a man-in-the-middle attack. |
+| Boundary Client Agent authentication does not persist across restarts | When you reboot, you are required to re-authenticate to the Client Agent before you can use transparent sessions. |
+| Windows shortcuts are mandatory | The Windows installer always installs Desktop and Start menu shortcuts. This is a known issue. Shortcuts will be optional in a future version of the installer. |
+| Windows installer prompts for restart | When you install Boundary, the Windows installer occasionally prompts you to restart your computer, however it is not necessary. |
+| Boundary Client Agent resumes on reboot | If the Client Agent is paused and the machine is rebooted, the Client Agent will be resumed after the reboot. |
+| Single-word aliases do not work on Windows | If you create an alias consisting of a single word without a dot (`.`), the alias will not work on Windows. |
+| Windows installer does not support partial installations | The Windows installer fails to start the Client Agent if the Desktop client is not installed at the same time. |
+
+## More information
+
+Refer to the following topics for more information:
+
+- [Aliases](/boundary/docs/concepts/aliases)
+- [Boundary Client Agent](/boundary/docs/api-clients/client-agent)
diff --git a/...tent/docs/configuration/session-recording/storage-providers/configure-minio.mdx b/...tent/docs/configuration/session-recording/storage-providers/configure-minio.mdx
@@ -30,6 +30,9 @@ When you determine storage requirements for the external bucket, you should cons
 
    You must associate the Boundary storage bucket with a MinIO storage bucket. A Boundary MinIO storage bucket contains the bucket name, endpoint URL, optional region, optional prefix, and the service account credentials needed to access the bucket. To enable credential rotation, you cannot add a Boundary storage bucket without a MinIO service account. You can disable credential rotation when you create the Boundary storage bucket.
 
+   At the time of the 0.18.0 release, the latest tested and supported MinIO version is `RELEASE.2024-10-02T17-50-4Z`.
+   Newer versions may work as well, but they have not been tested.
+
    <Note>
 
    At this time, the NetBSD operating system is not supported for the MinIO storage bucket.

diff --git a/...cs/configuration/session-recording/storage-providers/configure-s3-compliant.mdx b/...cs/configuration/session-recording/storage-providers/configure-s3-compliant.mdx
@@ -11,13 +11,22 @@ description: |-
 
 The [MinIO plugin](https://github.com/hashicorp/boundary-plugin-minio/) lets you configure S3-compliant storage providers for session recording.
 
+<a name="providers"></a>
 HashiCorp has tested and confirmed that you can configure the following S3-compliant storage products for session recording using the MinIO plugin:
 
-- [Hitachi Content Platform](#hitachi-content-platform-configuration)
+- [Hitachi Content Platform](https://trycontent.hitachivantara.com)
+
+   At the time of the 0.18.0 release, the latest tested and supported Hitachi Content Platform version is `2.6.0.0`.
+   Newer versions may work as well, but they have not been tested.
+
+- [Backblaze B2](https://www.backblaze.com/cloud-storage)
 
 You can also configure other providers' S3-compliant storage products for session recording storage.
 We will update the list of providers as we test them.
 
+The process for [configuring the Hitachi Content Platform](#hitachi-content-platform-configuration) is included below as an example.
+Configuring other S3-compliant storage products for use with session recording should be a similar process.
+
 ## Requirements
 
 Before you can create a storage bucket in Boundary, you must ensure that your environment meets certain requirements.
@@ -40,11 +49,10 @@ When you determine storage requirements for the external bucket, you should cons
 - A service account and access keys for the storage provider
 
    You must provide service account access keys when you configure a Boundary storage bucket later on.
-
    Refer to your storage provider's documentation to learn how to set up a service account.
 
 - The storage bucket must be configured with R/W access. If you use a
-  restricted IAM user policy, the following policy actions must be allowed at a minimum.
+  restricted IAM user policy, you must allow the following policy actions at a minimum.
 
    ```json
    {
@@ -73,7 +81,7 @@ When you determine storage requirements for the external bucket, you should cons
 
 HashiCorp has tested and confirmed that you can configure the Hitachi Content Platform for external session recording storage using the MinIO plugin.
 It is included as an example in this topic.
-You should be able to configure other S3-compliant storage providers to work for session recording storage as well, but we have not tested other providers.
+You should be able to configure other S3-compliant storage providers to work for session recording storage as well, but we have only tested a [limited number of providers](#providers).
 
 You must have an account with Hitachi Content Platform to create storage buckets.
 You can sign up for an account at the following URL:

diff --git a/website/content/docs/enterprise/supported-versions.mdx b/website/content/docs/enterprise/supported-versions.mdx
@@ -31,13 +31,29 @@ Customers are recommended to run the latest versions of Boundary in order to lev
 
 ## Control plane and client/cli compatibility
 
-The supported version compatibility between Boundary's control plane and Boundary clients/cli is the same as control plane and worker compatibility. Within a Boundary Enterprise deployment API backwards compatibility is only supported between the control plane and clients from the prior “major release”. Using clients on newer versions than the control plane they are registered with is not supported.
+The supported version compatibility between Boundary's control plane and Boundary clients/CLI is the same as control plane and worker compatibility. Within a Boundary Enterprise deployment API backwards compatibility is only supported between the control plane and clients from the prior “major release”. Using clients on newer versions than the control plane they are registered with is not supported.
 
 For example, Boundary clients version 0.14.0 are compatible with Boundary control plane running Boundary 0.15.0.
 However, they will not have compatibility once the control plane is updated to version 0.16.0 or above.
 Boundary clients version 0.16.0 are not compatible with Boundary control plane running Boundary 0.15.0 or lower.
 Customers are recommended to run the latest versions of Boundary in order to leverage the newest features and bug fixes.
 
+The Desktop client uses a different numbering scheme than the CLI and control plane.
+Refer to the table for the Desktop version that corresponds to the control plane version.
+
+| Desktop version | Control plane version |
+| --------------- | ----------- |
+| 2.1.0 | 0.17.0 |
+| 2.0.3 | 0.16.0 |
+| 2.0.2 | 0.15.3 |
+| 2.0.1 | 0.15.1 |
+| 2.0.0 | 0.15.0 |
+
+For example, the Desktop version 2.0.3 is compatible with version 0.17.0 of the control plane.
+But when the control plane is upgraded to 0.18.0, version 2.0.3 will no longer be officially supported.
+
+To view the Desktop version along with the corresponding CLI and control plane version, click **Boundary**, and then click **About Boundary** in the Desktop client.
+
 ## PostgreSQL support policy
 
 Boundary Enterprise will only support PostgreSQL version 13 and above at launch.