From 1f9063e0420ccbc27b455a6947616229276c9b95 Mon Sep 17 00:00:00 2001 From: Hugo Vieira Date: Mon, 12 Dec 2022 22:01:05 +0000 Subject: [PATCH] docs(target): Introduce direct address targets and explain tradeoffs --- CHANGELOG.md | 3 ++ website/content/docs/api-clients/cli.mdx | 4 +-- .../docs/concepts/domain-model/index.mdx | 24 ++++++++++++++- .../docs/concepts/domain-model/targets.mdx | 16 ++++++---- .../oss/installing/connect-to-dev-target.mdx | 29 ++++++++++++++----- .../content/docs/oss/installing/dev-mode.mdx | 4 ++- 6 files changed, 63 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a00d5d8be..5688772770 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,9 @@ Canonical reference for changes, improvements, and bugfixes for Boundary. ### New and Improved +* Direct Address Targets: You can now set an address directly on a target, + bypassing the need for host catalogs, host sets and hosts. + ([PR](https://github.com/hashicorp/boundary/pull/2613)) * Custom Response Headers: Adds ability to set api and ui response headers based on status code. Includes default secure CSP and other headers. ([PR](https://github.com/hashicorp/boundary/pull/2587)) diff --git a/website/content/docs/api-clients/cli.mdx b/website/content/docs/api-clients/cli.mdx index 105f852704..7e05d57b74 100644 --- a/website/content/docs/api-clients/cli.mdx +++ b/website/content/docs/api-clients/cli.mdx @@ -130,8 +130,8 @@ However, a target can be one of many types of targets, and a concrete implementation of a target is a `tcp` type of target. Therefore an extra parameter is required when creating or updating a target: -- `boundary targets tcp create` -- `boundary targets tcp update` +- `boundary targets create tcp` +- `boundary targets update tcp` This allows the CLI to perform proper presentation and validation of parameters and functions for the given type. diff --git a/website/content/docs/concepts/domain-model/index.mdx b/website/content/docs/concepts/domain-model/index.mdx index 12c8ae84a4..ac8d9cf3fb 100644 --- a/website/content/docs/concepts/domain-model/index.mdx +++ b/website/content/docs/concepts/domain-model/index.mdx @@ -51,7 +51,29 @@ The highest-level in Boundary utilizes the concepts of [Roles](/docs/concepts/do ## Target and Host Resources -Boundary exposes endpoints to users as [Targets](/docs/concepts/domain-model/targets). A target is a resource representing a networked service, with an associated set of permissions, that allows a user to connect and interact with Boundary within a single session. A target may contain references to [Host](/docs/concepts/domain-model/hosts) sources and [Credential](/docs/concepts/domain-model/credentials) sources. Users who access a target create an authorized session to one of its host sources with returned credentials from the target’s credential source. +Boundary exposes endpoints to users as [Targets](/docs/concepts/domain-model/targets). A target is a resource representing a networked service, with an associated set of permissions, that allows a user to connect and interact with Boundary within a single session. A target may contain references to [Host](/docs/concepts/domain-model/hosts) sources or an address, and [Credential](/docs/concepts/domain-model/credentials) sources. Users who access a target create an authorized session to its address or one of its host sources with returned credentials from the target’s credential source. + +A target exposes two distinct and mutually exclusive configuration paths for its +representation of a networked service: + +- Target with an address +- Target with host sources + +A target with an address represents a target that is set up with a single IP +address or DNS name directly on the target resource. This mechanism provides +benefits for new Boundary users and users who do not need the flexibility +provided by Hosts, Host Sets, and Host Catalogs. It is well suited for cases +where there are stand-alone hosts that should not be grouped together and +treated as equal from an access control point of view. Because of its +simplicity, using targets with an address is not recommended when there are a +either a large number of hosts and/or dynamic hosts. + +A target with host sources represents a target that has one or more [host +sets][] associated with it. It trades off the simplicity of directly setting an +address on a target with the flexibility and scalability of Hosts, Host Sets and +Host Catalogs for discovering and categorizing networked resources. We recommend +using targets with host sources for setting up Boundary in environments where a +significant number of resources exist. ### Summary of Resources diff --git a/website/content/docs/concepts/domain-model/targets.mdx b/website/content/docs/concepts/domain-model/targets.mdx index 56dfa11eb7..53db118719 100644 --- a/website/content/docs/concepts/domain-model/targets.mdx +++ b/website/content/docs/concepts/domain-model/targets.mdx @@ -19,11 +19,13 @@ A target can contain references to [host sets][] from [host catalogs][] which belong to the same project as the target. A target can contain references to [credential libraries][] from [credential stores][] which belong to the same project as the target. -A user can establish a session with a [host][] -in any host set referenced by the target -if the user has been assigned a [role][] -with the `authorize-session` [permission][] -for the target. +A target can contain an address +which is used by a session to connect to a networked resource. +A target cannot have an address and also reference host sources. +A user must be assigned a [role][] with the `authorize-session` [permission][] +for the target to +establish a session with a networked resource by way of an address, +or host in any host set referenced by the target. ## Attributes @@ -34,6 +36,10 @@ A target has the following configurable attributes: - `description` - (optional) +- `address` - (optional) + 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 targets have the following additional attributes: diff --git a/website/content/docs/oss/installing/connect-to-dev-target.mdx b/website/content/docs/oss/installing/connect-to-dev-target.mdx index c6fe921afb..b46eca4544 100644 --- a/website/content/docs/oss/installing/connect-to-dev-target.mdx +++ b/website/content/docs/oss/installing/connect-to-dev-target.mdx @@ -8,16 +8,32 @@ description: |- ## Connect to Your First Target The default target is a `tcp` target with a default port of `22` (which -corresponds to the default SSH port using TCP). The host sets for this target -contain the default host, which has the address `127.0.0.1`. When `boundary -connect` is executed against this target, the single available host will be -selected and a local authenticated proxy to the host is established on the +corresponds to the default SSH port using TCP). This target is set up with +`127.0.0.1` as its address. When you execute `boundary connect` against this +target, a local authenticated proxy to the address is established on the target's default port (`127.0.0.1:22`). ```shell-session $ boundary connect -target-id ttcp_1234567890 ``` +There is also a secondary `tcp` target with (`ttcp_0987654321`) which uses host +sets instead of an address. The host sets for this target contain the default +host, which has the address 127.0.0.1. When you execute `boundary connect` +against this target, the single available host will be selected and a local +authenticated proxy to the host is also established on the target's default port +(127.0.0.1:22). + +```shell-session +boundary connect -target-id ttcp_0987654321 +``` + +For the purpose of this guide, both of these targets accomplish the same goal, +however they have different purposes. Refer to the +[domain](/docs/concepts/domain-model/index) documentation for more information. + +For the rest of this guide, assume the default is used. + The output displays the address and port that your SSH client must utilize. In the next section the `ssh` connect helper is used to make it easier to connect to the target with a client. @@ -130,6 +146,7 @@ of `:22` to `:443`: $ boundary targets update tcp -default-port 443 -id ttcp_1234567890 Target information: + Address: 127.0.0.1 Created Time: Fri, 25 Sep 2020 18:35:47 PDT Description: Provides an initial target in Boundary ID: ttcp_1234567890 @@ -146,10 +163,6 @@ Target information: Parent Scope ID: o_1234567890 Type: project - Host Sets: - Host Catalog ID: hcst_1234567890 - ID: hsst_1234567890 - Attributes: Default Port: 443 ``` diff --git a/website/content/docs/oss/installing/dev-mode.mdx b/website/content/docs/oss/installing/dev-mode.mdx index da5493acd9..70f0c28fa4 100644 --- a/website/content/docs/oss/installing/dev-mode.mdx +++ b/website/content/docs/oss/installing/dev-mode.mdx @@ -42,7 +42,9 @@ connect to your first target: set](/docs/concepts/domain-model/host-sets) with default ID's of `hst_1234567890` and `hsst_1234567890` respectively. 1. A TCP [target](/docs/concepts/domain-model/targets) with a default ID of - `ttcp_1234567890`. + `ttcp_1234567890`, directly set-up with an address and port. +1. A TCP [target](/docs/concepts/domain-model/targets) with a default ID of + `ttcp_0987654321` using the previously mentioned static host set. The default ID suffixes can be overwritten or randomly generated, and there are many other dev mode controls. To see a complete list of these override flags,