docs(target): Introduce direct address targets and explain tradeoffs

2023-01-09 15:39:55 +00:00
1 parent 803cd278ae
commit 1f9063e042
@@ -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))
@@ -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.
@@ -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

@@ -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:
@@ -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
 ```
@@ -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,