Skip to content

Commit 8656e62

Browse files
rmainworkLeahMarieBush
rmainwork
and
LeahMarieBush
authored
Add boundary content to main (#1194)
Co-authored-by: Leah Bush <157434496+LeahMarieBush@users.noreply.github.com>
1 parent ccfdf51 commit 8656e62

File tree

5,281 files changed

+405349
-16
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

5,281 files changed

+405349
-16
lines changed

‎content/boundary/v0.1.x/content/docs/api-clients/api.mdx‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
layout: docs
3+
page_title: API
4+
sidebar_title: API
5+
description: |-
6+
Boundary's HTTP API standards
7+
---
8+
9+
# API
10+
11+
Boundary's API is a a JSON-based HTTP API that adheres to a set of standards that are rigidly followed. At its core, it is a standards-compliant JSON API for both input and output.
12+
13+
Before reading this page, it is useful to understand Boundary's [domain model](/docs/concepts/domain-model) to be aware of the terminology used here.
14+
15+
Boundary's API is also described via OpenAPI v2; the version corresponding to any tag of Boundary's source code can be found in Boundary's [GitHub repository](https://github.com/hashicorp/boundary/blob/main/internal/gen/controller.swagger.json).
16+
17+
Boundary's current API version is 1; all API paths begin with `/v1/`.
18+
19+
## Status Codes
20+
21+
- `2XX`: Boundary returns a code between `200` and `299` on success. Generally this is `200`, but implementations should be prepared to accept any `2XX` status code as indicating success. If a call returns a `2XX` code that is not `200`, it will follow well-understood semantics for those status codes.
22+
- `400`: Boundary returns `400` when a command cannot be completed due to invalid user input, except for a properly-formatted identifier that does not map to an existing resource, which will return a `404` as discussed below.
23+
- `401`: Boundary returns `401` if no authentication token is provided or if the provided token is invalid. A valid token that simply does not have permission for a resource will return a `403` instead. A token that is invalid or missing, but where the anonymous user (`u_anon`) is able to successfully perform the action, will not return a `401` but instead will return the result of the action.
24+
- `403`: Boundary returns `403` if a provided token was valid but does not have the grants required to perform the requested action.
25+
- `404`: Boundary returns `404` if a resource cannot be found. Note that this happens _prior_ to authentication/authorization checking in nearly all cases as the resource information (such as its scope, available actions, etc.) is a required part of that check. As a result, an action against a resource that does not exist will return a `404` instead of a `401` or `403`. While this could be considered an information leak, since IDs are randomly generated and this only discloses whether an ID is valid, it's tolerable as it allows for far simpler and more robust client implementation.
26+
- `405`: Boundary returns a `405` to indicate that the method (HTTP verb or custom action) is not implemented for the given resource.
27+
- `500`: Boundary returns `500` if an error occurred that is not (directly) tied to invalid user input. If a `500` is generated, information about the error will be logged to Boundary's server log but is not generally provided to the client.
28+
29+
## Path Layout
30+
31+
Boundary follows a predictable path layout. There are two fundamental types of URL paths, each supporting a different set of operations.
32+
33+
### Collections
34+
35+
Collections of resources are top level paths with plural English names for the resource, e.g. `/roles` and `/hosts`. Collections support the following operations:
36+
37+
- Creation of new resources within that collection
38+
- Listing of resources within that collection
39+
40+
All collection operations require supplying the enclosing resource. Depending on the collection type, this will be one of the following:
41+
42+
- A scope, indicating the scope in which an operation should take place. For instance, a POST to `/roles` would need to indicate whether the role should be created within the `global` scope or an org-level scope like `o_1234567890`.
43+
- A parent resource of the appropriate type. For instance, hosts and host sets are child resources of host catalogs. When creating a new host set within a host catalog, a POST to `/host-sets` would need to indicate the host catalog ID with which the host-set should be associated.
44+
45+
### Resources
46+
47+
Resources themselves are defined by ID specifiers within a collection path, e.g. `/roles/r_1234567890`. Resources support the following operations:
48+
49+
- Reading a resource's properties
50+
- Updating a resource's properties
51+
- Deleting a resource
52+
- Custom methods specific to a resource type
53+
54+
Depending on the resource type, various parameters may be available. Some are common across all resource types (e.g. `name` and `description`); others are available only for specific types. Further, some concrete-types of abstract resources include an opaque `attributes` JSON object with type-specific values.
55+
56+
For instance, an auth method is an abstract type; a `password` auth method is a concrete implementation of that type. When creating such an auth method, a `type` parameter will indicate that it should be the `password` type, while values specific to the `password` type auth method, such as minimum password length, will be contained within an `attributes` object.
57+
58+
## Methods
59+
60+
The following method conventions are used within Boundary's API:
61+
62+
### GET
63+
64+
`GET` is used for reading a resource or listing resources in a collection. The behavior depends on whether the `GET` is issued against a collection (`/roles`) or a singular resource (`/roles/r_1234567890`). In the former case it lists resources within the collection; in the latter it performs a read on that particular resource.
65+
66+
### POST
67+
68+
`POST` is used for creating a resource or performing custom actions against a resoruce. When creating a resource, `POST` is used against a collection (`/roles`). When performing a custom action, `POST` is used against a particular resource (`/roles/r_1234567890:set-principals`).
69+
70+
### PATCH
71+
72+
`PATCH` is used to update a resource's parameters. The following are behaviors to be aware of when using `PATCH`:
73+
74+
- In nearly all cases, a `version` parameter is required. This is used for check-and-set, to ensure that the update operation is being performed against a known resource. The version parameter is returned from a `GET` operation on the resource so the current version, along with the resource's other current values, can be looked up at any time.
75+
- Passing a JSON `null` for a parameter has the effect of reverting that parameter to its default. For some parameters (e.g. `name`) this will simply clear the value (as the default `name` for a resource is empty); for other parameters this will revert to the current defaults within Boundary.
76+
- All parameters specified as part of a `PATCH` operation will be considered to be parameters that should be updated.
77+
78+
### DELETE
79+
80+
`DELETE` is used for deleting a specific resource, and is only used against a particular resource path.

‎content/boundary/v0.1.x/content/docs/api-clients/cli.mdx‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
layout: docs
3+
page_title: CLI
4+
sidebar_title: CLI
5+
description: |-
6+
Boundary's CLI behavior
7+
---
8+
9+
# CLI
10+
11+
Boundary's CLI has predictable behavior throughout its various commands. This
12+
page details the common patterns in used in order to help users make better use
13+
of the CLI.
14+
15+
## Completion
16+
17+
Before detailing how parameters work, it's useful to note that Boundary's CLI
18+
supports autocompletion, which allows tab completion of commands, flags, and in
19+
some cases the parameters to those flags.
20+
21+
This can be installed via the CLI itself:
22+
23+
`boundary config autocomplete install`
24+
25+
If you want to install it manually, for Bash, the following line in a
26+
`~/.bash_profile` or similar file will work:
27+
28+
`complete -C /path/to/boundary boundary`
29+
30+
## Keyring Token storage
31+
32+
Boundary uses various mechanisms, depending on platform, to allow for secure
33+
storage of authentication tokens for later use. Each platform has a
34+
platform-specific option (which on Windows and macOS are the default);
35+
[pass](https://www.passwordstore.org/) is also available on all platforms. On
36+
all platforms, setting `-keyring-type` to `none` (or setting it via
37+
`BOUNDARY_KEYRING_TYPE`) disables storage and retrieval of the token.
38+
39+
Additionally, more than one token can be stored or retrieved at once via the
40+
`-token-name` flag or `BOUNDARY_TOKEN_NAME` env var. This allows for storing
41+
tokens used by different Boundary installations, or other needs.
42+
43+
### Windows
44+
45+
On Windows, the Windows credential store (`wincred`) is used.
46+
47+
Available keyring types:
48+
49+
* `wincred` (default)
50+
* `pass`
51+
* `none`
52+
53+
### macOS
54+
55+
On macOS, Keychain is used via `/usr/bin/security`. (Using this binary allows us
56+
to keep the Boundary binary statically linked, which we prefer.)
57+
58+
Available keyring types:
59+
60+
* `keychain` (default)
61+
* `pass`
62+
* `none`
63+
64+
### Other platforms
65+
66+
On all other platforms, the default is `pass`. However, if an implementation of
67+
the [freedesktop.org secret
68+
service](https://specifications.freedesktop.org/secret-service/latest/) is
69+
available (via `gnome-keyring`, `kwallet`, or others) it can be used.
70+
71+
Available keyring types:
72+
73+
* `pass` (default)
74+
* `secret-service`
75+
* `none`
76+
77+
## Mapping to Collections and Sub-Types
78+
79+
Generally speaking, Boundary's CLI commands map to the collections they operate
80+
on. For instance, when operating on roles, the command will be `boundary roles
81+
...`.
82+
83+
As a result, the patterns for reading, deleting, and listing are predictable:
84+
85+
* `boundary <collection> read`
86+
* `boundary <collection> delete`
87+
* `boundary <collection> list`
88+
89+
`read` and `delete` will always operate on a particular resource identifier, so
90+
will always take in an `-id` parameter. `list` operates on collections so will
91+
either take a `-scope-id` parameter or, depending on type, a higher level
92+
resource identifier, e.g. `-auth-method-id`.
93+
94+
Creating and updating resources may take an extra parameter if the resource type
95+
is abstract, that is, if the type cannot be operated on directly but must be
96+
operated on through an implementation. As an example, a role is not an abstract
97+
type, and does not have various implementations of it. As a result, a role can
98+
be operated on directly:
99+
100+
* `boundary roles create`
101+
* `boundary roles update`.
102+
103+
However, a target can be one of many types of targets, and a concrete
104+
implementation of a target is a `tcp` type of target. Therefore an extra
105+
parameter is required when creating or updating a target:
106+
107+
* `boundary targets tcp create`
108+
* `boundary targets tcp update`
109+
110+
This allows the CLI to perform proper presentation and validation of parameters
111+
and functions for the given type.
112+
113+
Similar to `read`, `update` operates on an existing target so will always take
114+
an `-id` parameter. Similar to `list`, `create` operates on a collection so will
115+
either take a `-scope-id` parameter or a parameter defining the parent resource.
116+
117+
## Parameter Handling
118+
119+
All parameters specified on the CLI are specified as a Go-style flag with a
120+
single dash, e.g. `-id`. The arguments to those flags can be specified via an
121+
equals sign, as in `-id=r_1234567890`, or a space, like `-id r_1234567890`.
122+
123+
To see available parameters, pass the `-h` flag to any command.
124+
125+
Flags are semi-position dependent. The flags must come _after_ the command
126+
definition, but are otherwise order independent.
127+
128+
For instance, the following are equivalent:
129+
130+
* `boundary roles create -scope-id global -name foo`
131+
* `boundary roles create -name foo -scope-id global`
132+
133+
But the following results in an error:
134+
135+
* `boundary roles -name foo -scope-id global create`
136+
137+
This applies to `-h` as well!
138+
139+
### Clearing/Defaulting Values
140+
141+
On the CLI, you can use `null` as a value to indicate to Boundary that you want
142+
to unset a value, reverting to Boundary's default. In many cases this default
143+
will be empty (e.g. for a `name` or `description` parameter) but in other cases
144+
it's not. For instance, for a password auth method's minimum password length,
145+
the default is not `0` but rather `8`. Additionally, attempting to set string
146+
values to the empty string `""` is usually not an allowed operation, since when
147+
set to a specific value it must be non-empty. Using `null` to clear a value
148+
ensures you'll revert to Boundary's recommended default.
149+
150+
~> `null` is used because of the fact that the API is JSON. Using `null` as the
151+
value causes the key for the parameter to be inserted into the eventual API
152+
call's JSON object but with the value set to the JSON `null`. This in turn
153+
informs the Controller that this value should be set to its default. Keep in
154+
mind that this is not a direct translation to database `NULL` semantics!
155+
156+
### Connection Options
157+
158+
Every command that results in an API call contains a set of flags that control
159+
connection options, which control TLS and other settings for the connection.
160+
161+
### Client Options
162+
163+
Every command that results in an API call contains a set of flags that control
164+
client options. Some notable options:
165+
166+
* `output-curl-string`: This will format the command that would have been run as
167+
a string using `curl` that can be used directly on the command line. This is a
168+
great way to discover how CLI functions map to API calls.
169+
170+
* `token-name`: When the CLI authenticates, it stores the token in the
171+
platform-specific OS credential store. By using the `token-name` parameter, more
172+
than one token can be stored at a time. Specifying this parameter at
173+
authentication time uses the given name as part of the key for storage;
174+
specifying it for any other command will cause the corresponding token to be
175+
used for that call.
176+
177+
* `recovery-config`: This is used to specify a configuration file that contains
178+
the information necessary to access a KMS configured to be used for the recovery
179+
workflow within a Boundary controller.
180+
181+
### Output Options
182+
183+
Nearly every command supports having its success output be formatted as JSON via
184+
`-format json`. For commands that result in an API call, the JSON output will be
185+
the exact output from the controller. If using the output of the CLI in scripts
186+
or as parameters to other tools, _always_ use formatted output. The default text
187+
output is meant for human users and the formatting or the information included
188+
within that output from the original JSON may change at any time.

‎content/boundary/v0.1.x/content/docs/api-clients/desktop.mdx‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
layout: docs
3+
page_title: Boundary Desktop
4+
sidebar_title: Desktop
5+
description: |-
6+
Get up and running with Boundary Desktop
7+
---
8+
9+
# Boundary Desktop
10+
11+
-> Boundary Desktop is currently an Alpha release still undergoing final testing before its official release. Should you experience any bugs or lack of desired functionality, please let us know so that we can evaluate a fix. You can open an issue at https://github.com/hashicorp/boundary/issues/new/choose. Your help is greatly appreciated!
12+
13+
Boundary Desktop is a standalone application that provides a simple interface
14+
for browsing and connecting to targets on your local computer (macOS currently
15+
supported). Launch a session in Boundary Desktop and then make a connection
16+
using your favorite tooling!
17+
18+
## Getting Started
19+
20+
-> If you're running Boundary for the first time, [download the latest binary](https://www.boundaryproject.io/downloads)
21+
and run it in `dev` mode locally so you can have a server to run against:
22+
23+
```shell-session
24+
$ boundary dev
25+
```
26+
27+
### Install Boundary Desktop
28+
29+
1. Download the latest .dmg installer from our [releases page](https://releases.hashicorp.com/boundary-desktop). Alternatively, if you're a homebrew user, you can run `brew install hashicorp-boundary-desktop`
30+
1. Double-click the downloaded .dmg to run the installer
31+
1. Drag and drop Boundary into the applications folder
32+
![](/img/boundary-desktop-drag-to-install.png)
33+
34+
### Run Boundary Desktop
35+
36+
1. Open the Boundary Desktop application
37+
![](/img/boundary-desktop-open.png)
38+
1. You'll be prompted for the Boundary server origin, this is the URL for the client
39+
to connect to the Boundary API. If you are running a local `dev` mode server, this
40+
URL will be `http://localhost:9200`
41+
![](/img/boundary-desktop-origin.png)
42+
1. You can now login to Boundary. We're using a `dev` mode server in this example with the
43+
username `admin` and the password `password`
44+
![](/img/boundary-desktop-login.png)
45+
1. After logging in, you should see the targets your user is authorized to connect to. Since
46+
we are using a `dev` mode server we see the default generated target for `127.0.0.1:22`
47+
![](/img/boundary-desktop-landing.png)
48+
49+
### Connect!
50+
51+
-> The rest of this example assumes you're running Boundary in `dev` mode.
52+
53+
1. Click on `connect` next to the default target. A pop-up window will display the local
54+
address of the proxy and the ephemeral port for the session
55+
![](/img/boundary-desktop-connect.png)
56+
1. Navigate to the `Sessions` pane and you'll see this session is in `pending` state because we
57+
haven't made a connection to it yet (but will!)
58+
![](/img/boundary-desktop-pending.png)
59+
60+
-> The next step assumes you have a SSH server running that the default target will connect to.
61+
62+
1. On the CLI, `ssh` to the target using the local ephemeral port created in the previous step
63+
64+
```shell-session
65+
$ ssh -p 49250 127.0.0.1
66+
The authenticity of host '[127.0.0.1]:49250 ([127.0.0.1]:49250)' can't be established.
67+
ECDSA key fingerprint is SHA256:glO05n2iT8Roqak5G63gMKnW8qsE0lxy0MPWcWC7iqg.
68+
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
69+
Warning: Permanently added '[127.0.0.1]:49250' (ECDSA) to the list of known hosts.
70+
Password:
71+
Last login: Thu Feb 11 17:49:09 2021
72+
$
73+
```
74+
75+
1. Navigate back to the sessions view and you'll see this session is now active
76+
![](/img/boundary-desktop-active.png)
77+
1. Click `Cancel` to cancel the session and you'll see the status go to `cancelling` briefly, then `terminated`
78+
![](/img/boundary-desktop-terminated.png)
79+
1. Navigate back to the CLI and you'll see your SSH session has closed

0 commit comments

Comments
 (0)