From 28de3d712b72273aa2873cc4a4c38f14f104e6a5 Mon Sep 17 00:00:00 2001 From: Johan Brandhorst-Satzkorn Date: Fri, 21 Jul 2023 12:12:55 -0700 Subject: [PATCH] Connect option docs (#3424) * docs: add ssh connect helper Really just splits this up into a separate heading. We will add more connect helpers as we go. * docs: add RDP connect helper * docs: add postgres connect helper * docs: add http connect helper * docs: add kube connect helper * docs: remove duplicate mention of helpers * docs: Copy edits to dev-mode topic * docs: Copy edits to hcp topic * docs: Minor copy edits --------- Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> --- .../dev-mode/connect-to-dev-target.mdx | 181 ++++++++++++++++-- .../hcp/get-started/connect-to-target.mdx | 179 +++++++++++++++-- 2 files changed, 331 insertions(+), 29 deletions(-) diff --git a/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx b/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx index 049cada26..583739e06 100644 --- a/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx +++ b/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx @@ -54,7 +54,9 @@ within the authorized session. When you are finished making connections, simply Boundary includes connect helpers that automatically accept host SSH key prompts for you. These are written as `boundary connect `. -In the following example, the helper will automatically execute `ssh` for you, +### SSH connect helper + +In the following example, the helper automatically executes `ssh` for you, filling in the local address and port. An expected host ID is set to avoid warnings on future connections when a different port is allocated automatically. A host key must still be accepted upon first connect. @@ -63,8 +65,21 @@ A host key must still be accepted upon first connect. $ boundary connect ssh -target-id ttcp_1234567890 ``` + + If you want to pass additional flags to the SSH client, add them to the command -line separated by a double-dash; anything after the double dash will be passed +line separated by a double dash; anything after the double dash is passed to the executed client. For instance: ```shell-session @@ -82,6 +97,150 @@ specify a username other than your currently logged-in user. This ensures that regardless of your `-style` choice, the username is properly passed to the executed client, and you don't need to figure out the syntax yourself. +### RDP connect helper + +The RDP helper attempts to decide which RDP client to use +depending on your operating system. On Windows, it uses `mstsc.exe`. On +Mac, it uses `open`. Other operating systems are not currently supported. + +```shell-session +$ boundary connect rdp -target-id ttcp_eTcZMueUYv +``` + +This command executes the RDP client and establishes the connection through +Boundary. + + + +The RDP helper also supports a `-style` flag to allow you to override the +default RDP client. Recognized styles are `mstsc` and `open`. + +### PostgreSQL connect helper + +The PostgreSQL helper executes `psql`, and passes information such as the username and +database name from the command line. + +```shell-session +$ boundary connect postgres -target-id ttcp_eTcZMueUYv -username admin -dbname postgres +``` + + + +The PostgreSQL helper automatically injects brokered credentials, allowing you +to access the PostgreSQL instance without knowing the username and password. + +```shell-session +$ boundary connect postgres -target-id ttcp_eTcZMueUYv -dbname postgres +``` + + + +The helper also supports a `-style` flag to allow you to override the +default PostgreSQL client. The only recognized style is `psql`. + +### HTTP connect helper + +The HTTP connect helper executes `curl`, passing information such as the HTTP path, +method, verb, and others. It can be useful to call API endpoints through the Boundary +proxy. In the example below, we call a weather API endpoint to get the rain forecast for +New York for the next few days. + +```shell-session +$ boundary connect http -target-id ttcp_VlpkajEuuf -path '/v1/forecast?latitude=40.7143&longitude=-74.006&daily=precipitation_sum&timezone=America%2FNew_York' +``` + + + +The HTTP helper supports several flags: + +- `host`: Specifies the host value to use, overriding the endpoint address from the session information. + +- `method`: Specifies the method to use. If you do not set this value, the helper uses the client's default method. + +- `path`: Specifies a path that is appended to the generated URL. + +- `scheme`: Specifies the scheme to use. The default is https. + +The helper also supports a `-style` flag to allow you to override the +default HTTP client. The only recognized style is `curl`. + +### Kubernetes connect helper + +The Kubernetes connect helper executes `kubectl` by proxying the call through Boundary. +It can be useful to access a Kubernetes cluster that does not publicly expose its API server. +To pass subcommands to `kubectl`, use `--` followed by the command you want to pass. In +this example, we're calling `kubectl top node`: + +```shell-session +$ boundary connect kube -target-id ttcp_Yq0QCUMSe2 -- top node +``` + + + +The Kubernetes helper supports several flags: + +- `host`: Specifies the host value to use, overriding the endpoint address from the session information. + +- `scheme`: Specifies the scheme to use. The default is https. + +The helper also supports a `-style` flag to allow you to override the +default Kubernetes client. The only recognized style is `kubectl`. + ## Select targets When using `boundary connect` you must identify the target used for connecting. @@ -105,18 +264,10 @@ $ boundary connect ssh -target-name "Generated target" -target-scope-name "Gener ## Built-in vs. exec -Boundary comes with built-in wrappers for popular layer 7 connection protocols, -such as: - -- `ssh`: defaults to the local SSH client (`ssh`) -- `postgres`: defaults to the official Postgres CLI client (`psql`) -- `rdp`: defaults to the built-in Windows RDP client (`mstsc`) -- `http`: defaults to `curl` -- `kube`: defaults to `kubectl` - -However, `boundary connect` can accommodate executing clients even when there is -no built-in support for a specific client using `-exec`. The `-exec` flag is a -very powerful tool, allowing you to wrap Boundary TCP sessions in your preferred +We've seen the built-in connect helpers above, however, `boundary connect` +can accommodate executing clients even when there is no built-in support +for a specific client using `-exec`. The `-exec` flag is a very powerful +tool, allowing you to wrap Boundary TCP sessions in your preferred client. You can use this flag to create an authenticated proxy to almost anything. @@ -217,4 +368,4 @@ proxy details. See our [basic administration workflows](/boundary/tutorials/oss-administration) -for in depth discussion on managing scopes, targets, identities, and sessions. \ No newline at end of file +for in depth discussion on managing scopes, targets, identities, and sessions. diff --git a/website/content/docs/hcp/get-started/connect-to-target.mdx b/website/content/docs/hcp/get-started/connect-to-target.mdx index e0bcf3547..dff185fd5 100644 --- a/website/content/docs/hcp/get-started/connect-to-target.mdx +++ b/website/content/docs/hcp/get-started/connect-to-target.mdx @@ -57,7 +57,9 @@ within the authorized session. When you are finished making connections, simply Boundary includes connect helpers that automatically accept host SSH key prompts for you. These are written as `boundary connect `. -In the following example, the helper will automatically execute `ssh` for you, +#### SSH connect helper + +In the following example, the helper automatically executes `ssh` for you, filling in the local address and port. An expected host ID is set to avoid warnings on future connections when a different port is allocated automatically. A host key must still be accepted upon first connect. @@ -66,8 +68,21 @@ A host key must still be accepted upon first connect. $ boundary connect ssh -target-id ttcp_eTcZMueUYv ``` + + If you want to pass additional flags to the SSH client, add them to the command -line separated by a double-dash; anything after the double dash will be passed +line separated by a double dash; anything after the double dash is passed to the executed client. For instance: ```shell-session @@ -85,6 +100,150 @@ specify a username other than your currently logged-in user. This ensures that regardless of your `-style` choice, the username is properly passed to the executed client, and you don't need to figure out the syntax yourself. +#### RDP connect helper + +The RDP helper attempts to decide which RDP client to use +depending on your operating system. On Windows, it uses `mstsc.exe`. On +Mac, it uses `open`. Other operating systems are not currently supported. + +```shell-session +$ boundary connect rdp -target-id ttcp_eTcZMueUYv +``` + +This command executes the RDP client and establishes the connection through +Boundary. + + + +The RDP helper also supports a `-style` flag to allow you to override the +default RDP client. Recognized styles are `mstsc` and `open`. + +#### PostgreSQL connect helper + +The PostgreSQL helper executes `psql`, and passes information such as the username and +database name from the command line. + +```shell-session +$ boundary connect postgres -target-id ttcp_eTcZMueUYv -username admin -dbname postgres +``` + + + +The PostgreSQL helper automatically injects brokered credentials, allowing you +to access the PostgreSQL instance without knowing the username and password. + +```shell-session +$ boundary connect postgres -target-id ttcp_eTcZMueUYv -dbname postgres +``` + + + +The helper also supports a `-style` flag to allow you to override the +default PostgreSQL client. The only recognized style is `psql`. + +#### HTTP connect helper + +The HTTP connect helper executes `curl`, passing information such as the HTTP path, +method, verb, and others. It can be useful to call API endpoints through the Boundary +proxy. In the example below, we call a weather API endpoint to get the rain forecast for +New York for the next few days. + +```shell-session +$ boundary connect http -target-id ttcp_VlpkajEuuf -path '/v1/forecast?latitude=40.7143&longitude=-74.006&daily=precipitation_sum&timezone=America%2FNew_York' +``` + + + +The HTTP helper supports several flags: + +- `host`: Specifies the host value to use, overriding the endpoint address from the session information. + +- `method`: Specifies the method to use. If you do not set this value, the helper uses the client's default method. + +- `path`: Specifies a path that is appended to the generated URL. + +- `scheme`: Specifies the scheme to use. The default is https. + +The helper also supports a `-style` flag to allow you to override the +default HTTP client. The only recognized style is `curl`. + +#### Kubernetes connect helper + +The Kubernetes connect helper executes `kubectl` by proxying the call through Boundary. +It can be useful to access a Kubernetes cluster that does not publicly expose its API server. +To pass subcommands to `kubectl`, use `--` followed by the command you want to pass. In +this example, we're calling `kubectl top node`: + +```shell-session +$ boundary connect kube -target-id ttcp_Yq0QCUMSe2 -- top node +``` + + + +The Kubernetes helper supports several flags: + +- `host`: Specifies the host value to use, overriding the endpoint address from the session information. + +- `scheme`: Specifies the scheme to use. The default is https. + +The helper also supports a `-style` flag to allow you to override the +default Kubernetes client. The only recognized style is `kubectl`. + ## Select targets When using `boundary connect` you must identify the target used for connecting. @@ -108,18 +267,10 @@ $ boundary connect ssh -target-name "Generated target" -target-scope-name "Gener ## Built-in vs. exec -Boundary comes with built-in wrappers for popular layer 7 connection protocols, -such as: - -- `ssh`: defaults to the local SSH client (`ssh`) -- `postgres`: defaults to the official Postgres CLI client (`psql`) -- `rdp`: defaults to the built-in Windows RDP client (`mstsc`) -- `http`: defaults to `curl` -- `kube`: defaults to `kubectl` - -However, `boundary connect` can accommodate executing clients even when there is -no built-in support for a specific client using `-exec`. The `-exec` flag is a -very powerful tool, allowing you to wrap Boundary TCP sessions in your preferred +We've seen the built-in connect helpers above, however, `boundary connect` +can accommodate executing clients even when there is no built-in support +for a specific client using `-exec`. The `-exec` flag is a very powerful +tool, allowing you to wrap Boundary TCP sessions in your preferred client. You can use this flag to create an authenticated proxy to almost anything.