Boundary documentation: content cleanup in prep for devdot migration (#2249)

* cleaning up docs

* Update website/content/docs/concepts/domain-model/groups.mdx

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>

* Update website/content/docs/concepts/domain-model/managed-groups.mdx

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>

* Update website/content/docs/concepts/domain-model/roles.mdx

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>

* Update website/content/docs/concepts/domain-model/scopes.mdx

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>

* Update website/content/docs/concepts/domain-model/sessions.mdx

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>

* Update website/content/docs/configuration/worker/pki-worker.mdx

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>

* Update website/content/docs/getting-started/deploy-and-login.mdx

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
jimlambrt-worker-dag
Loann Le 4 years ago committed by GitHub
parent 194b3af678
commit d5633952db
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -14,7 +14,7 @@ of the CLI.
## CLI Command Structure
There are a number of command and subcommand options available.
To see all available command options, run `boundary -h`
To see all available command options, run `boundary -h`
and to see all available subcommand options run `boundary <command> -h`.
Below is the typical structure for most Boundary CLI commands:
@ -28,7 +28,7 @@ boundary <command> <subcommand> [options] [args]
#### Examples:
The following shows use of the [`-addr`](/docs/api-clients/cli#addr) flag to specify which Boundary controller to send the request to.
The following shows use of the [`-addr`](/docs/api-clients/cli#addr) flag to specify which Boundary controller to send the request to.
```shell-session
$ boundary authenticate password \
@ -174,7 +174,7 @@ values to the empty string `""` is usually not an allowed operation, since when
set to a specific value it must be non-empty. Using `null` to clear a value
ensures you'll revert to Boundary's recommended default.
~> `null` is used because of the fact that the API is JSON. Using `null` as the
~> **Note:** `null` is used because of the fact that the API is JSON. Using `null` as the
value causes the key for the parameter to be inserted into the eventual API
call's JSON object but with the value set to the JSON `null`. This in turn
informs the Controller that this value should be set to its default. Keep in
@ -183,7 +183,7 @@ mind that this is not a direct translation to database `NULL` semantics!
### Connection Options
Every command that results in an API call contains a set of flags that control
connection options, which control TLS and other settings for the connection.
connection options, which control TLS and other settings for the connection.
You can also run `boundary dev -h` to see the available connection options.
- `-addr=<string>`: Address of the Boundary controller, as a complete URL (e.g.

@ -64,7 +64,7 @@ Now let's create an auth method client using the base client from above:
amClient := authmethods.NewClient(client)
```
~> This creates a shallow copy of the base client. Modifications made to the client via `am.ApiClient()` will not be reflected in the base client.
~> **Note:** This creates a shallow copy of the base client. Modifications made to the client via `am.ApiClient()` will not be reflected in the base client.
The last thing you'll need is the ID of the auth method in Boundary. You can get this on the CLI
with:

@ -51,3 +51,7 @@ A group has the following configurable attributes:
The following services are relevant to this resource:
- [Group Service](/api-docs/group-service)
## Tutorial
Refer to the [Manage Users and Groups with HCP Boundary](https://learn.hashicorp.com/tutorials/boundary/hcp-manage-users-groups) tutorial to learn how to complete user management related tasks.

@ -55,3 +55,7 @@ OIDC managed groups have the following additional attributes:
The following services are relevant to this resource:
- [Managed Group Service](/api-docs/managed-group-service)
## Tutorial
Refer to the [Manage Users and Groups with HCP Boundary](https://learn.hashicorp.com/tutorials/boundary/hcp-manage-users-groups) tutorial to learn how to complete user management related tasks.

@ -46,3 +46,7 @@ A role has the following configurable attributes:
The following services are relevant to this resource:
- [Role Service](/api-docs/role-service)
## Tutorial
Refer to the [Managed Roles and Permissions with HCP Boundary](https://learn.hashicorp.com/tutorials/boundary/hcp-manage-roles) tutorial to learn how to create a role in Boundary.

@ -24,7 +24,7 @@ The global scope can directly contain:
## Organizations
~> Within the software itself and elsewhere in the documentation, Boundary reliably uses "org" instead of "organization". Among other reasons, this removes ambiguity between different regional spellings of the word. It is spelled out here in the domain model for completeness and to ensure its intent is clear.
~> **Note:** Within the software itself and elsewhere in the documentation, Boundary reliably uses "org" instead of "organization". Among other reasons, this removes ambiguity between different regional spellings of the word. It is spelled out here in the domain model for completeness and to ensure its intent is clear.
An org is a scope directly contained by the global scope.
There can be multiple orgs within the global scope.
@ -84,3 +84,7 @@ A scope has the following configurable attributes:
The following services are relevant to this resource:
- [Scope Service](/api-docs/scope-service)
## Tutorial
Refer to the [Manage Scopes with HCP Boundary](https://learn.hashicorp.com/tutorials/boundary/hcp-manage-scopes) tutorial to learn how to create an org scope and a project scope.

@ -102,3 +102,7 @@ Changes to a user's permissions do not effect existing sessions.
The following services are relevant to this resource:
- [Session Service](/api-docs/session-service)
## Tutorial
Refer to the[] Manage Sessions with HCP Boundary](https://learn.hashicorp.com/tutorials/boundary/hcp-manage-sessions) tutorial to learn how to start, view, and cancel a session.

@ -7,7 +7,7 @@ description: |-
This page describes how to filter events written to Boundary event sinks.
~> This feature was introduced in Boundary 0.5.0.
~> **Note:** This feature was introduced in Boundary 0.5.0.
# Event Filtering
@ -15,15 +15,15 @@ Starting in Boundary 0.5.0, a variety of event types (error, observation,
system, etc) are emitted from Boundary. Boundary events can be emitted in
several formats including [cloudevents](https://github.com/cloudevents/spec) and
[hclog](https://github.com/hashicorp/go-hclog), and can be encoded as text and
json.
json.
Boundary allows you to configure any number of
[sinks](/docs/configuration/events/overview), where these events will be
written. When configuring an event sink, you can specify [common sink
parameters](/docs/configuration/events/common) which include both
`allow_filters` and `deny_filters` which use the standard [filter
syntax](/docs/concepts/filtering) used
elsewhere in Boundary.
syntax](/docs/concepts/filtering) used
elsewhere in Boundary.
Example events encoded as cloudevents-text. The first event is a system event
and the second event is an observation event.
@ -66,8 +66,8 @@ and the second event is an observation event.
}
```
If I wanted to filter an event sink which was configured for every event type to
only include the above events, I might use the following sink configuration:
To filter an event sink which was configured for every event type to
only include the above events, use the following sink configuration:
```
sink "stderr" = {
name = "all-events"
@ -88,10 +88,9 @@ boundary dev \
-event-allow-filter '"/data/request_info/path" contains ":authenticate"' \
-event-allow-filter '"/data/op" contains ".createClientConn"'
```
~> Double quotes are part of the filter syntax; when using the CLI, it is likely
Double quotes are part of the filter syntax; when using the CLI, it is likely
easier to surround the filter with single quotes than to deal with escaping
double quotes.
~> Both `-event-allow-filter` and `-event-deny-filter` command flags are
~> **Note:** Both `-event-allow-filter` and `-event-deny-filter` command flags are
supported for the `boundary dev` command.

@ -9,7 +9,7 @@ This page describes how to use filters with OIDC managed groups. It assumes that
the reader is familiar with the general [filter syntax][] as well as with
[OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html).
~> This feature was introduced in Boundary 0.3.0.
~> **Note:** This feature was introduced in Boundary 0.3.0.
[filter syntax]: /docs/concepts/filtering

@ -8,7 +8,7 @@ description: |-
This page describes how to use filters when listing resources. This can be used
to reduce the returned set of resources when performing a list operation.
~> This feature is intended to provide a userful service to clients; it does not
~> **Note:** This feature is intended to provide a userful service to clients; it does not
affect the database queries generated for the operation and as such is not
designed to provide greater efficiency.
@ -63,13 +63,13 @@ within the filter at `/item`.
On the CLI a filter can be given via `-filter`.
~> Double quotes are part of the filter syntax; when using the CLI, it is likely
~> **Tip:** Double quotes are part of the filter syntax; when using the CLI, it is likely
easier to surround the filter with single quotes than to deal with escaping
double quotes.
When using the HTTP API, it is a `filter` query parameter.
~> Ensure that the query parameter is properly escaped! Most HTTP libraries will
~> **Tip:** Ensure that the query parameter is properly escaped! Most HTTP libraries will
do this for you. If you're having trouble, try using the `-output-curl-string`
flag with the Boundary CLI:

@ -40,7 +40,7 @@ As HCL is JSON-compatible, this turns into an input JSON value of:
}
```
Note that this is the canonical format, as it maps closely to the filter
~> **Note:** This is the canonical format, as it maps closely to the filter
structure. However, for compatibility with some other systems, it is also
possible to specify the tags in a pure key=value style:
@ -120,7 +120,7 @@ nested under `tags` and include a `name` value:
}
```
!> If an expression fails due to a key not being found within the input data,
~> **Note:** If an expression fails due to a key not being found within the input data,
the worker is not included in the final set, so ensure that all workers that
should match a given filter are populated with tags referenced in the filter
string. As a corollary, it is not possible to distinguish between a worker that

@ -78,13 +78,13 @@ TLS establishment is performed as follows:
for a single client to make multiple connections within a session, without the
credentials being usable via a different client:
- If the worker was not given a TOFU token in step 5, the worker submits the
9. If the worker was not given a TOFU token in step 5, the worker submits the
value to the Controller. The Controller verifies (via a database transaction)
that the session has not had a different TOFU token submitted prior and stores
it. Otherwise it's rejected, and so is the connection, as a possible replay
attack.
- If the Worker was given a TOFU token in step 5, it checks to see whether the
10. If the Worker was given a TOFU token in step 5, it checks to see whether the
token values match. If not, the connection is rejected as a possible replay
attack.

@ -13,7 +13,7 @@ Systems](/docs/configuration/kms) that protect the base encryption keys used
for various functions. This page describes the various KMS key purposes that
Boundary supports and how they are used within the system.
~> Boundary does not currently support rotation of its internal keys, but this
~> **Note:** Boundary does not currently support rotation of its internal keys, but this
will be supported in a future version. External keys can be rotated so long as
the original keys remain available for decryption; full support for rotating
these will come in a future version as well.
@ -31,7 +31,7 @@ with the KMS key marked for `root` purpose.
The current scoped DEKs and their purposes are detailed below:
~> Management of these keys is handled entirely internally; the information
~> **Note:** Management of these keys is handled entirely internally; the information
provided in this section is purely for informational purposes.
- `database`: This is the general-purpose DEK used to encrypt values within the
@ -66,7 +66,7 @@ cannot be replayed by an adversary, and also to ensure that each operation must
be individually authenticated by a client so that revoking access to the KMS has
an immediate result.
~> It is not required for this `kms` configuration block to exist in the
~> **Note:** It is not required for this `kms` configuration block to exist in the
Controller's configuration file. It's best practice to leave it out except when
actually needed, and to use change control capabilities to ensure that the
configuration file modification is authorized. After it's no longer needed, the
@ -76,7 +76,7 @@ On the client side, a user can use the `-recovery-config` flag with any
operation on the CLI to specify a configuration file containing a suitable `kms`
block. This functionality is also accessible via the Go SDK.
~> Requests authorized via this mechanism will show a user of `u_recovery`. This
~> **Note:** Requests authorized via this mechanism will show a user of `u_recovery`. This
mechanism _cannot_ be used to authorize a session, as there is no uniquely
identifying user information available.

@ -5,7 +5,7 @@ description: |-
The AEAD KMS configures AEAD-specific parameters.
---
~> This is mostly used for `dev` workflows or testing. The key will be exposed
~> **Note:** This is mostly used for `dev` workflows or testing. The key will be exposed
to anyone that can view the configuration file. If using this KMS, consider
using `boundary config encrypt` to encrypt all but the `config` KMS and using an
external KMS for `config` purposes.

@ -70,5 +70,5 @@ AliCloud authentication values:
* `ALICLOUD_SECRET_KEY`
```
Note: The client uses the official AliCloud SDK and will use environment credentials,
The client uses the official AliCloud SDK and will use environment credentials,
the specified credentials, or RAM role credentials in that order.

@ -9,7 +9,7 @@ description: |-
The Transit configures Boundary to use Vault's Transit Secret Engine for key management.
The Transit KMS is activated by the presence of a `kms "transit"` block in Boundary's configuration file
The Transit KMS is activated by the presence of a `kms transit` block in Boundary's configuration file
## `transit` Example
@ -54,11 +54,11 @@ These parameters apply to the `kms` stanza in the Vault configuration file:
decryption. This may also be supplied using the `TRANSIT_WRAPPER_KEY_NAME`
environment variable.
- `mount_path` `(string: <required>)`: The mount path to the transit secret engine.
- `mount_path` `(string: <required>)`: The mount path to the transit secret engine.
This may also be supplied using the `TRANSIT_WRAPPER_MOUNT_PATH` environment
variable.
- `namespace` `(string: "")`: The namespace path to the transit secret engine.
- `namespace` `(string: "")`: The namespace path to the transit secret engine.
This may also be supplied using the `VAULT_NAMESPACE` environment variable.
- `disable_renewal` `(string: "false")`: Disables the automatic renewal of the token

@ -9,7 +9,7 @@ description: |-
The Unix listener configures Boundary to listen on a Unix domain socket.
~> This is only available for listeners for `"api"` and `"cluster"` purpose.
~> **Note:** This is only available for listeners for `api` and `cluster` purpose.
Unix sockets cannot currently be used for `"proxy"` purpose on a Worker.
```hcl
@ -88,7 +88,7 @@ allowed.
### TLS
~> `tls` parameters are valid for `api` and `ops` listeners. `cluster`
and `proxy` connections use their own ephemeral TLS stacks. For more
and `proxy` connections use their own ephemeral TLS stacks. For more
information, see [the connections security concepts
page](https://www.boundaryproject.io/docs/concepts/security/connections-tls).

@ -101,7 +101,7 @@ kms "aead" {
[`initial_upstreams`](/docs/configuration/worker/overview#initial_upstreams)
are used to connect to upstream Boundary clusters.
## Further Reading
## Resources
For more on how `tags{}` in the above configuration are used to facilitate
routing to the correct target, refer to the [Worker

@ -11,7 +11,7 @@ PKI Workers authenticate to Boundary using a certificate-based method, allowing
for worker deployment without using a shared KMS.
PKI Workers require an accessible directory defined by `auth_storage_path` for
credential storage.
credential storage.
Example (not safe for production!):
@ -57,3 +57,7 @@ worker {
```
[kms workers]: /docs/configuration/worker/kms-worker
## Tutorial
Refer to the [Self-Managed Worker Registration with HCP Boundary](https://learn.hashicorp.com/tutorials/boundary/hcp-manage-workers) tutorial to learn how to register and manage PKI workers.

@ -57,7 +57,7 @@ within the authorized session. When you are finished making connections, simply
### Using Connect Helpers
Boundary includes connect helpers that automatically accept host SSH key prompts
for you. These are written as `boundary connect <subcommand>`.
for you. These are written as `boundary connect <subcommand>`.
In the following example, the helper will automatically execute `ssh` for you,
filling in the local address and port. An expected host ID is set to avoid
@ -221,8 +221,12 @@ proxy details.
/>
</video>
## Tutorial
Refer to the [Connect to your First Target](https://learn.hashicorp.com/tutorials/boundary/hcp-getting-started-connect?in=boundary/hcp-getting-started) tutorial for steps on how to create a host catalog, host set, and a target in Boundary.
## Next Steps
See our [basic administration
workflows](https://learn.hashicorp.com/collections/boundary/hcp-administration)
for in depth discussion on managing scopes, targets, identities, and sessions.
Refer to our [basic administration
workflows](https://learn.hashicorp.com/collections/boundary/hcp-administration) tutorial series
for in depth discussions on managing scopes, targets, identities, and sessions.

@ -15,10 +15,10 @@ underlying systems or operations.
To deploy an HCP Boundary instance:
1. Navigate to [HashiCorp Cloud Platform](https://portal.cloud.hashicorp.com/)
and login using your credentials.
and login using your credentials.
1. Click the **Boundary (Beta)** tab, and then and click **Deploy Boundary** on
the right-hand pane.
the right-hand pane.
1. Fill out the following form details:
@ -39,30 +39,30 @@ To deploy an HCP Boundary instance:
Once the deployment is complete, the HCP Boundary instance can be accessed
directly from the HCP Boundary portal using the credentials created during
setup.
setup.
1. From the HCP Boundary portal page, click the **Open Admin UI** button.
1. From the HCP Boundary portal page, click the **Open Admin UI** button.
1. Enter the admin username and password you created when you deployed the new
instance, and click **Authenticate**.
1. The **Welcome to Boundary** setup wizard will launch automatically.
1. The **Welcome to Boundary** setup wizard will launch automatically.
There are two options for Boundarys initial setup:
- Quick setup
- Manual
![Setup Wizard](/img/setup-wizard.png)
The **Quick setup** is recommended for new users, and generates a set of initial
resources to assist in connecting to your first target.
resources to assist in connecting to your first target.
![Setup Wizard](/img/setup-wizard-target.png)
The **Manual** setup drops the user directly into Boundary, without any
provisioned resources.
Upon completion of the setup wizard, you will be logged into your HCP Boundary
instance's Global scope via the web UI. This is the default scope for all new
Boundary clusters.
@ -169,12 +169,12 @@ provider "boundary" {
}
```
To find your environments `base_url`:
To find your environments `base_url`:
1. In the HCP portal, open the **Boundary Overview** page.
1. Click the **copy icon** in the **Copy this into Boundary Desktop** section. This copies your environments Boundary **Origin URL**.
To find your environments default `auth_method_id`:
To find your environments default `auth_method_id`:
1. In your HCP Boundary portal, click the Admin UI button.
1. Log in to the Admin Console by entering the admin username and password you
@ -185,6 +185,11 @@ To find your environments default `auth_method_id`:
</Tab>
</Tabs>
## Tutorial
- Refer to the [Create a Boundary Instance on HCP](https://learn.hashicorp.com/tutorials/boundary/hcp-getting-started-create) tutorial to learn how to deploy a Boundary instance.
- Refer to the [Install Boundary Desktop](https://learn.hashicorp.com/tutorials/boundary/hcp-getting-started-desktop-app) tutorial to learn how to use the Boundary desktop to connect to a running HCP Boundary instance.
## Next Steps

@ -6,16 +6,17 @@ description: Getting started with Boundary
# Getting Started
Before getting started with Boundary, it's important to understand a few key concepts. Please consult our [Boundary concepts](/docs/concepts) page to familiarize yourself with Boundary's architecture, and terminology.
Before getting started with Boundary, it's important to understand a few key concepts. Please consult our [Boundary concepts](/docs/concepts) page to familiarize yourself with Boundary's architecture and terminology.
## Requirements
The Getting Started section uses HCP Boundary, a HashiCorp hosted and fully-managed version of the Boundary product.
The Getting Started section uses HCP Boundary, a HashiCorp hosted and fully-managed version of the Boundary product.
To get started with HCP Boundary, users need:
- A [HashiCorp Cloud Platform](https://portal.cloud.hashicorp.com/sign-up) account
- [Installation](https://learn.hashicorp.com/tutorials/boundary/hcp-getting-started-install?in=boundary/hcp-getting-started) of Boundary CLI
- A [Boundary binary](https://www.boundaryproject.io/downloads) in your `$PATH`
- Optionally, an [installation of Boundary Desktop](https://learn.hashicorp.com/tutorials/boundary/hcp-getting-started-desktop-app)
If you prefer to Get Started on your local machine, refer to [Run and Login in Dev Mode](/docs/oss/installing/run-and-login). For more information on Boundary OSS and self-managed installations, refer to [Boundary OSS](/docs/oss/index).
If you prefer to get started on your local machine, refer to [Run and Login in Dev Mode](/docs/oss/installing/run-and-login). For more information on Boundary OSS and self-managed installations, refer to [Boundary OSS](/docs/oss).

@ -25,3 +25,7 @@ and resilient. It can run in clouds, on-premise, or within secure enclaves.
Boundary does not require an agent to be installed on the end host.
![How Boundary Works](/img/how-boundary-works.png)
## Tutorial
Refer to the [Get Started with self-hosted Boundary](https://learn.hashicorp.com/collections/boundary/oss-getting-started) tutorial series to learn how to install and configure Boundary.

@ -20,7 +20,7 @@ Boundary deployment through Prometheus.
The metrics uses the [OpenMetric
exposition](https://prometheus.io/docs/instrumenting/exposition_formats/#openmetrics-text-format)
format which can be read by
[Prometheus](https://prometheus.io/docs/introduction/overview/).
[Prometheus](https://prometheus.io/docs/introduction/overview/).
### Controller
@ -29,7 +29,7 @@ by controllers.
| Name | Description |
|---------------------------------------------------------------|-----------------------------------------------|
| `boundary_controller_api_http_request_duration_seconds` | Histogram of latencies for HTTP requests. |
| `boundary_controller_api_http_request_duration_seconds` | Histogram of latencies for HTTP requests. |
| `boundary_controller_api_http_request_size_bytes` | Histogram of request sizes for HTTP requests. |
| `boundary_controller_api_http_response_size_bytes` | Histogram of response sizes for HTTP requests. |
| `boundary_controller_cluster_grpc_request_duration_seconds` | Histogram of latencies for requests made to the gRPC service running on the cluster listener. |
@ -69,7 +69,7 @@ measurements collected.
| `method` | The name of the method on the HTTP request. For example "GET", “POST”, “DELETE”. |
#### Metrics for gRPC requests include the following labels:
#### Metrics for gRPC requests include the following labels:
| Label | Description |
|-----------------|-----------------------------------------------------------------|
@ -78,7 +78,7 @@ measurements collected.
| `grpc_code` | The grpc [status code](https://github.com/grpc/grpc-go/blob/master/codes/codes.go) in human-readable format. For example, `OK`, `IllegalArgument`, `Unknown`. |
## Example configuration
## Example configuration
Defining a listener stanza in the config file is sufficient for enabling metrics
reporting in Boundary. For details on what fields are allowed in this stanza,
@ -96,6 +96,6 @@ listener "tcp" {
## Tutorial
Refer to [Prometheus
Refer to the [Prometheus
Metrics](https://learn.hashicorp.com/tutorials/boundary/prometheus-metrics)
tutorial for a step-by-step introduction to metrics.

@ -55,3 +55,7 @@ Boundary enables a single sign-on access model with authentication from trusted
### Session Monitoring
Boundary provides session monitoring capabilities that give security administrators visibility into user access. Sessions are logged and consumable via the Boundary administrator UI as well as business intelligence (BI) and security information and event management (SIEM) tools.
## Tutorial
Refer to HashicCorp Learn for [Boundary](https://learn.hashicorp.com/boundary) to gain access to Boundary's series of featured tutorials to learn how to set up, configure, and administer Boundary.

Loading…
Cancel
Save