From 8e6e2fc735c47ac70e05a222e12fa6b9a5106869 Mon Sep 17 00:00:00 2001 From: Todd Knight Date: Mon, 5 Oct 2020 09:23:04 -0700 Subject: [PATCH] Session Workflow use "connect" instead of "proxy" and fix few typos for other workflow docs. (#524) --- .../common-workflows/manage-identities.mdx | 2 +- .../docs/common-workflows/manage-scopes.mdx | 10 +- .../docs/common-workflows/manage-sessions.mdx | 111 ++++++++---------- .../docs/common-workflows/manage-targets.mdx | 2 +- 4 files changed, 61 insertions(+), 64 deletions(-) diff --git a/website/content/docs/common-workflows/manage-identities.mdx b/website/content/docs/common-workflows/manage-identities.mdx index f675797ab..5b8ff8b85 100644 --- a/website/content/docs/common-workflows/manage-identities.mdx +++ b/website/content/docs/common-workflows/manage-identities.mdx @@ -145,7 +145,7 @@ resource "boundary_account" "my_user" { -## Create User +## Create a User Next, create a user at the organization scope. diff --git a/website/content/docs/common-workflows/manage-scopes.mdx b/website/content/docs/common-workflows/manage-scopes.mdx index 0e299fa81..a9f3fa715 100644 --- a/website/content/docs/common-workflows/manage-scopes.mdx +++ b/website/content/docs/common-workflows/manage-scopes.mdx @@ -21,7 +21,7 @@ In this example, we're going to create two scopes, a project and an organization generated resources in `dev` mode. Please make sure to use the resource ID's that are generated when running this example. For example, if you run `boundary users create`, use the resource ID of the user seen in stdout, not the ID in the example command. -## Create a Organization +## Create an Organization An organization lives in the global scope. In this example, we're going to create an organization. In doing so, we're going to opt for automated role creation during scope generation in order to simplify management of the scope by the user. @@ -62,6 +62,7 @@ Click save and view the org in the main Boundary landing page: + ```hcl resource "boundary_scope" "org" { scope_id = "global" @@ -74,6 +75,7 @@ resource "boundary_scope" "org" { + ## Create a Project Next, we're going to add a project scope to our organization. Again, we're going to opt for automated role creation to simplify management of this scope. @@ -81,6 +83,7 @@ Next, we're going to add a project scope to our organization. Again, we're going + ```bash $ boundary scopes create -scope-id o_0MkQUfE9jA -name my_project -description 'My frist project' @@ -102,6 +105,7 @@ Scope information: + Navigate to your org in the UI and click `new` project: ![](/img/manage-scopes-project-undefined.png) @@ -114,6 +118,7 @@ View the newly created project: + ```hcl resource "boundary_scope" "project" { name = "my_project" @@ -126,4 +131,5 @@ resource "boundary_scope" "project" { ``` - \ No newline at end of file + + diff --git a/website/content/docs/common-workflows/manage-sessions.mdx b/website/content/docs/common-workflows/manage-sessions.mdx index da1b2dfe0..f32dbeff6 100644 --- a/website/content/docs/common-workflows/manage-sessions.mdx +++ b/website/content/docs/common-workflows/manage-sessions.mdx @@ -7,44 +7,18 @@ description: How to manage Boundary sessions # Manage Sessions -[Sessions](/docs/concepts/domain-model/sessions) are Boundary resources which enables connecting to a [target](/docs/concepts/domain-model/target). A target allows Boundary users to define an endpoint with a default-port and a protocol to establish a session. Unless specified with a `-host-id` flag when establishing a session, Boundary will choose one [host](/docs/concepts/domain-model/hosts) from the target's host-sets to connect to at random. +[Sessions](/docs/concepts/domain-model/sessions) are Boundary resources created when connecting to a [target](/docs/concepts/domain-model/target). A target allows Boundary users to define an endpoint with a default-port and a protocol to establish a session. Unless specified with a `-host-id` flag when establishing a session, Boundary will choose one [host](/docs/concepts/domain-model/hosts) from the target's host-sets to connect to at random. -In this section, we'll show you the basics of how to start a session in Boundary on the CLI and the admin console. +In this section, we'll show you the basics of how to start a session, view the session details, and cancel a session in Boundary using the CLI. -We assume you're running Boundary in dev mode and have a default target of `ttcp_1234567890`. We also assume you've logged in on the command line and the admin console. See the output of `boundary dev` for these login values. +We assume you're running Boundary in dev mode using the default target resource of `ttcp_1234567890`. We also assume you've authenticated using the CLI. See the output of `boundary dev` for these login values. -## Authorize with a target +## Start a Session -For this example, we're going to authorize that you are able to connect to a target which results in an Authorization Token being returned which can be used to connect to the session through the proxy. - - +Connecting to a target creates a session in Boundary. To demonstrate what a session looks like we are going to connect to a TCP target with a default port of 22 for SSH access. ```bash -$ boundary targets authorize-session -id ttcp_1234567890 - -Target information: - Authorization Token: $LONG_STRING_OF_TEXT - Created Time: 2020-09-30T15:18:14-07:00 - Host ID: hst_1234567890 - Scope ID: p_1234567890 - Session ID: s_h7vBIhH5SZ - Target ID: ttcp_1234567890 - Type: tcp - User ID: u_1234567890 -``` - - - -~> You can also provide a -host-id flag in the request above to connect to a specific host. The chosen host must be contained in one of the host sets associated with the target. - -## Connect to the session - -Once we have received an Authorization Token a Boundary session has been created and is waiting to proxy connection to the target. We'll now connect our local proxy to the Boundary deployment. - - - -```bash -$ boundary proxy -authz $LONG_STRING_OF_TEXT +$ boundary connect ssh -target-id ttcp_1234567890 -- Proxy listening information: Address: 127.0.0.1 @@ -55,22 +29,11 @@ Proxy listening information: Session ID: s_h7vBIhH5SZ ``` - +For more information regarding different ways to connect to a target behind Boundary see [Connect to Target](/docs/getting-started/connect-to-target) under Getting Started and [Advanced Session Establishment](#advanced-session-establishment) below. -With the above address and port information we can now connect to our local proxy and have our tcp traffic sent through the boundary system. +## View Sessions -```bash -$ ssh 127.0.0.1 -p 61991 -... -``` - -For SSH connections we'll likely receive a notice that the authenticity of the host can't be established. - -## Viewing Sessions - -Beyond establishing sessions we can also view and cancel sessions. Here we'll view all sessions that have recently happened in the project scope that are default target is in. - - +View all sessions which Boundary has for the project `p_1234567890` by listing them. ```bash $ boundary sessions list -scope-id p_1234567890 @@ -85,11 +48,7 @@ Session information: Target ID: ttcp_1234567890 ``` - - -We can get a more detailed view of this specific session by reading it. - - +We can get a more detailed view of a specific session by reading it. ```bash $ boundary sessions read -id s_h7vBIhH5SZ @@ -122,16 +81,11 @@ Session information: End Time: Wed, 30 Sep 2020 15:18:35 MST Start Time: Wed, 30 Sep 2020 15:18:14 MST Status: pending - ``` - +## Cancel a Session -## Cancelling Sessions - -To shut down a session the person initiating the connection can disconnect all connections or a request can be sent to Boundary to cancel a specific session. - - +To cancel a session the person initiating the connection can disconnect all connections, or a request can be sent to Boundary to cancel it. ```bash $ boundary sessions cancel -id s_h7vBIhH5SZ @@ -170,6 +124,43 @@ Session information: Status: pending ``` - +Boundary then cancels the session and move it into a "Terminated" state. -Boundary will then cancel the session and move it into a "Terminated" state. +## Advanced Session Establishment + +Above we discussed connecting to a target using the `boundary connect` command. In addition to this we can create a session to a target and connect to that session in separate steps. This is accomplished using the `boundary targets authorize-session` command, which generates a authorization token that users can use to start a session via `boundary proxy` at their own convenience. + +```bash +$ boundary targets authorize-session -id ttcp_1234567890 + +Target information: + Authorization Token: $LONG_STRING_OF_TEXT + Created Time: 2020-09-30T15:18:14-07:00 + Host ID: hst_1234567890 + Scope ID: p_1234567890 + Session ID: s_h7vBIhH5SZ + Target ID: ttcp_1234567890 + Type: tcp + User ID: u_1234567890 +``` + +Note: You can also provide a -host-id flag in the request above which ensures connecting using the provided Authorization Token will connect you to this specific host. + +```bash +$ boundary proxy -authz $LONG_STRING_OF_TEXT + +Proxy listening information: + Address: 127.0.0.1 + Connection Limit: 1 + Expiration: Wed, 30 Sep 2020 23:18:14 MST + Port: 61991 + Protocol: tcp + Session ID: s_h7vBIhH5SZ +``` + +With the above address and port information we can now connect to our local proxy and have our tcp traffic sent through the Boundary system. + +```bash +$ ssh 127.0.0.1 -p 61991 +... +``` diff --git a/website/content/docs/common-workflows/manage-targets.mdx b/website/content/docs/common-workflows/manage-targets.mdx index 92e54dcbc..72a726895 100644 --- a/website/content/docs/common-workflows/manage-targets.mdx +++ b/website/content/docs/common-workflows/manage-targets.mdx @@ -150,7 +150,7 @@ resource "boundary_host_set" "postgres" { -## Define Target +## Define a Target