From d49b7ae629c4f887401ecceaca7042fc7674cdae Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Fri, 26 May 2023 13:11:43 -0400 Subject: [PATCH] docs: Restructure table of contents (#3230) * docs: Restructure table of contents * docs: Copy edits to Develop/Get started sections * docs: Add index to HCP Boundary section * docs: Move OSS/Install section to top-level * docs: Move Concepts above Configuration --- .../docs/{oss => }/developing/building.mdx | 8 +- .../docs/{oss => }/developing/index.mdx | 6 +- .../content/docs/{oss => }/developing/ui.mdx | 8 +- .../dev-mode}/connect-to-dev-target.mdx | 6 +- .../dev-mode}/dev-mode.mdx | 4 - .../dev-mode}/run-and-login.mdx | 6 +- .../docs/getting-started/installing/index.mdx | 10 - .../getting-started/installing/production.mdx | 231 ---------- .../get-started}/connect-to-target.mdx | 2 +- .../get-started}/deploy-and-login.mdx | 6 +- website/content/docs/hcp/index.mdx | 17 + .../high-availability.mdx | 0 .../installing => install-boundary}/index.mdx | 0 .../no-gen-resources.mdx | 0 .../postgres.mdx | 0 .../reference-architectures.mdx | 0 .../systemd.mdx | 0 .../docs/{oss => }/operations/health.mdx | 16 +- .../docs/{oss => }/operations/index.mdx | 2 +- .../docs/{oss => }/operations/metrics.mdx | 14 +- website/data/docs-nav-data.json | 403 +++++++++--------- website/redirects.js | 96 +++++ 22 files changed, 355 insertions(+), 480 deletions(-) rename website/content/docs/{oss => }/developing/building.mdx (93%) rename website/content/docs/{oss => }/developing/index.mdx (73%) rename website/content/docs/{oss => }/developing/ui.mdx (77%) rename website/content/docs/{oss/installing => getting-started/dev-mode}/connect-to-dev-target.mdx (98%) rename website/content/docs/{oss/installing => getting-started/dev-mode}/dev-mode.mdx (93%) rename website/content/docs/{oss/installing => getting-started/dev-mode}/run-and-login.mdx (97%) delete mode 100644 website/content/docs/getting-started/installing/index.mdx delete mode 100644 website/content/docs/getting-started/installing/production.mdx rename website/content/docs/{getting-started => hcp/get-started}/connect-to-target.mdx (99%) rename website/content/docs/{getting-started => hcp/get-started}/deploy-and-login.mdx (98%) create mode 100644 website/content/docs/hcp/index.mdx rename website/content/docs/{oss/installing => install-boundary}/high-availability.mdx (100%) rename website/content/docs/{oss/installing => install-boundary}/index.mdx (100%) rename website/content/docs/{oss/installing => install-boundary}/no-gen-resources.mdx (100%) rename website/content/docs/{oss/installing => install-boundary}/postgres.mdx (100%) rename website/content/docs/{oss/installing => install-boundary}/reference-architectures.mdx (100%) rename website/content/docs/{oss/installing => install-boundary}/systemd.mdx (100%) rename website/content/docs/{oss => }/operations/health.mdx (96%) rename website/content/docs/{oss => }/operations/index.mdx (97%) rename website/content/docs/{oss => }/operations/metrics.mdx (96%) diff --git a/website/content/docs/oss/developing/building.mdx b/website/content/docs/developing/building.mdx similarity index 93% rename from website/content/docs/oss/developing/building.mdx rename to website/content/docs/developing/building.mdx index c973c5f27d..24e8bdac1f 100644 --- a/website/content/docs/oss/developing/building.mdx +++ b/website/content/docs/developing/building.mdx @@ -1,10 +1,10 @@ --- layout: docs -page_title: Documentation -description: Building Boundary +page_title: Build Boundary +description: Build Boundary from source --- -# Building Boundary +# Build Boundary Building Boundary from source requires: @@ -28,7 +28,7 @@ currently-pinned version via `make build-ui`. Once you've built Boundary, the binary will be available at `/bin/boundary`. Move this binary to somewhere in your `$PATH` such as `/usr/local/bin`. -## Cross Platform Build +## Cross-platform build If you need to cross compile boundary for another OS or architecture, use the [GOOS and GOARCH](https://github.com/hashicorp/boundary/blob/master/scripts/build.sh#L26) environment variable to set this. Example: `$ GOOS=linux GOARCH=amd64 make install` diff --git a/website/content/docs/oss/developing/index.mdx b/website/content/docs/developing/index.mdx similarity index 73% rename from website/content/docs/oss/developing/index.mdx rename to website/content/docs/developing/index.mdx index 7010905814..e9c285505e 100644 --- a/website/content/docs/oss/developing/index.mdx +++ b/website/content/docs/developing/index.mdx @@ -1,10 +1,10 @@ --- layout: docs -page_title: Developing Boundary -description: Developing Boundary +page_title: Develop Boundary +description: Develop Boundary --- -# Developing Boundary +# Develop Boundary The side-bar contains some common development tasks, but for the most up-to-date information about developing Boundary, please consult our [project on GitHub](https://github.com/hashicorp/boundary) for more information. diff --git a/website/content/docs/oss/developing/ui.mdx b/website/content/docs/developing/ui.mdx similarity index 77% rename from website/content/docs/oss/developing/ui.mdx rename to website/content/docs/developing/ui.mdx index 51a6232002..4fe220a984 100644 --- a/website/content/docs/oss/developing/ui.mdx +++ b/website/content/docs/developing/ui.mdx @@ -1,15 +1,15 @@ --- layout: docs -page_title: Developing the UI -description: Developing the Boundary User Interface +page_title: Develop the UI +description: Develop the Boundary user interface --- -# Developing the Boundary User Interface +# Develop the Boundary user interface For detailed instructions and the most up-to-date information on developing the Boundary admin UI, please consult [the project README on GitHub](https://github.com/hashicorp/boundary-ui). -## Run a Local Fork of the UI Locally in Dev Mode +## Run a local fork of the UI locally in Dev Mode If you're developing the Boundary UI locally you can point a dev mode server at a local checkout of the repo without building it into the binary. We call this diff --git a/website/content/docs/oss/installing/connect-to-dev-target.mdx b/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx similarity index 98% rename from website/content/docs/oss/installing/connect-to-dev-target.mdx rename to website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx index b1de62fe03..d818e1bdca 100644 --- a/website/content/docs/oss/installing/connect-to-dev-target.mdx +++ b/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx @@ -1,11 +1,11 @@ --- layout: docs -page_title: Connect to Dev Mode Target +page_title: Connect to your first target description: |- Connecting to your first target --- -## Connect to Your First Target +# 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). This target is set up with @@ -52,7 +52,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 `. +for you. These are written as `boundary connect `. 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 diff --git a/website/content/docs/oss/installing/dev-mode.mdx b/website/content/docs/getting-started/dev-mode/dev-mode.mdx similarity index 93% rename from website/content/docs/oss/installing/dev-mode.mdx rename to website/content/docs/getting-started/dev-mode/dev-mode.mdx index 1b3ee1e86a..4bcbe6186d 100644 --- a/website/content/docs/oss/installing/dev-mode.mdx +++ b/website/content/docs/getting-started/dev-mode/dev-mode.mdx @@ -6,10 +6,6 @@ description: Getting started with Boundary OSS in Dev mode # What is Dev Mode? -Before getting started with Boundary OSS, it's important to understand a few key -concepts. Please consult our [Boundary concepts](/boundary/docs/concepts) page to -familiarize yourself with Boundary's architecture and terminology. - Dev mode is a method for getting started with Boundary quickly for testing and learning purposes. As the name implies, dev mode is not a production installation method, and provides a way to get Boundary running with a Postgres diff --git a/website/content/docs/oss/installing/run-and-login.mdx b/website/content/docs/getting-started/dev-mode/run-and-login.mdx similarity index 97% rename from website/content/docs/oss/installing/run-and-login.mdx rename to website/content/docs/getting-started/dev-mode/run-and-login.mdx index f7b190cb24..b823ed87c7 100644 --- a/website/content/docs/oss/installing/run-and-login.mdx +++ b/website/content/docs/getting-started/dev-mode/run-and-login.mdx @@ -1,11 +1,11 @@ --- layout: docs -page_title: Run and Login +page_title: Run and log in to Boundary description: |- How to run Boundary services in dev mode and login for the first time. --- -# Run and Login to Boundary +# Run and log in to Boundary To start Boundary in dev mode: @@ -13,7 +13,7 @@ To start Boundary in dev mode: $ boundary dev ``` -## Login to Boundary +## Log in to Boundary Boundary uses a predictable login name (`admin`) and password (`password`) in dev mode. These can be overridden, or randomly generated, with flags to diff --git a/website/content/docs/getting-started/installing/index.mdx b/website/content/docs/getting-started/installing/index.mdx deleted file mode 100644 index a29e1e7fe7..0000000000 --- a/website/content/docs/getting-started/installing/index.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: docs -page_title: Installing Boundary -description: |- - How to install boundary. ---- - -# Overview - -This section covers installing Boundary for development and production modes of operation. diff --git a/website/content/docs/getting-started/installing/production.mdx b/website/content/docs/getting-started/installing/production.mdx deleted file mode 100644 index 2f5b132a2d..0000000000 --- a/website/content/docs/getting-started/installing/production.mdx +++ /dev/null @@ -1,231 +0,0 @@ ---- -layout: docs -page_title: Production Installation -description: |- - How to install Boundary in a production environment ---- - -# Production Installation - -Installing Boundary in a production setting requires prerequisits for infrastructure. At the most basic level, Boundary operators should run a minimum of 3 controllers and 3 workers. Running 3 of each server type gives a fundamental level of high availability for the control plane (controller), as well as bandwidth for number of sessions on the data plane (worker). Both server type should be ran in a fault tolerant setting, that is, in a self-healing environment such as an auto-scaling group. The documentation here does not cover self-healing infrastructure and assumes the operator has their preferred scheduling methods for these environments. - -## Network Requirements - -- Client -> Controller port is :9200 -- Worker -> Controller port is :9201 -- Client -> Worker port is :9202 -- Workers must have a route and port access to the targets which they service - -## Architecture - -The general architecture for the server infrastructure requires 3 controllers and 3 workers. The documentation here uses virtual machines running on Amazon EC2 as the example environment, but this use -case can be extrapolated to almost any cloud platform to suit operator needs: - -![](/img/production.png) - -As shown above, Boundary is broken up into its controller and worker server components across 3 [EC2 instances](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance), in -3 separate [subnets](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/subnet), in three separate availability zones, with the controller API and UI being publically exposed by an [application load balancer (ALB)](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb). The worker and controller VM's are in independent [auto-scaling groups](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/autoscaling_group), allowing them to maintain their exact capacity. - -Boundary requires an external [Postgres](https://www.postgresql.org/) and [KMS](https://aws.amazon.com/kms/). In the example above, we're using AWS managed services for these components. For Postgres, we're using [RDS](https://aws.amazon.com/rds/) and for KMS we're using Amazon's [Key Management Service](https://aws.amazon.com/kms/). - -## Architecture Breakdown - -### API and Console Load Balancer - -Load balancing the controller allows operators to secure the ingress to the Boundary system. We recommend placing all Boundary server's in private networks and using load balancing tecniques to expose services such as the API and administrative console to public networks. In the production architecture, we recommend load balancing using a layer 7 load balancer and further constraining ingress to that load balancer with layer 4 constraints such as [security groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) or [IP tables](https://wiki.archlinux.org/index.php/Iptables). - -For general configuration, we recommend the following: - -- HTTPS listener with valid TLS certificate for the domain it's serving or TLS passthrough -- Health check port should use :9200 with TCP protocol - -### Controller Configuration - -When running Boundary controller as a service we recommend storing the file at `/etc/boundary-controller.hcl`. A `boundary` user and group should exist to manage this configuration file and to further restrict who can read and modify it. - -Example controller configuration: - -```hcl -# Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.html -disable_mlock = true - -# Controller configuration block -controller { - # This name attr must be unique! - name = "demo-controller-${count.index}" - # Description of this controller - description = "A controller for a demo!" -} - -# API listener configuration block -listener "tcp" { - # Should be the address of the NIC that the controller server will be reached on - address = "${self.private_ip}:9200" - # The purpose of this listener block - purpose = "api" - # Should be enabled for production installs - tls_disable = true - # Enable CORS for the Admin UI - cors_enabled = true - cors_allowed_origins = ["*"] -} - -# Data-plane listener configuration block (used for worker coordination) -listener "tcp" { - # Should be the IP of the NIC that the worker will connect on - address = "${self.private_ip}:9201" - # The purpose of this listener - purpose = "cluster" - # Should be enabled for production installs - tls_disable = true -} - -# Root KMS configuration block: this is the root key for Boundary -# Use a production KMS such as AWS KMS in production installs -kms "aead" { - purpose = "root" - aead_type = "aes-gcm" - key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung=" - key_id = "global_root" -} - -# Worker authorization KMS -# Use a production KMS such as AWS KMS for production installs -# This key is the same key used in the worker configuration -kms "aead" { - purpose = "worker-auth" - aead_type = "aes-gcm" - key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" - key_id = "global_worker-auth" -} - -# Recovery KMS block: configures the recovery key for Boundary -# Use a production KMS such as AWS KMS for production installs -kms "aead" { - purpose = "recovery" - aead_type = "aes-gcm" - key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" - key_id = "global_recovery" -} - -# Database URL for postgres. This can be a direct "postgres://" -# URL, or it can be "file://" to read the contents of a file to -# supply the url, or "env://" to name an environment variable -# that contains the URL. -database { - url = "postgresql://boundary:boundarydemo@${aws_db_instance.boundary.endpoint}/boundary" -} -``` - -### Worker Configuration - -```hcl -listener "tcp" { - purpose = "proxy" - tls_disable = true -} - -worker { - # Name attr must be unique - name = "demo-worker-${count.index}" - description = "A default worker created demonstration" - initial_upstreams = [ - "${aws_instance.controller[0].private_ip}", - "${aws_instance.controller[1].private_ip}", - "${aws_instance.controller[2].private_ip}" - ] -} - -# must be same key as used on controller config -kms "aead" { - purpose = "worker-auth" - aead_type = "aes-gcm" - key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" - key_id = "global_worker-auth" -} -``` - -name must be unique! - -### Installation - -`TYPE` below can be either `worker` or `controller`. - -1. `/etc/boundary-${TYPE}.hcl`: Configuration file for the boundary service - See above example configurations. - -2. `/usr/local/bin/boundary`: The Boundary binary - Can build from https://github.com/hashicorp/boundary or download binary from our release pages. - -3. `/etc/systemd/system/boundary-${TYPE}.service`: Systemd unit file for the Boundary service - Example: - -``` -[Unit] -Description=${NAME} ${TYPE} - -[Service] -ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl -User=boundary -Group=boundary -LimitMEMLOCK=infinity -Capabilities=CAP_IPC_LOCK+ep -CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK - -[Install] -WantedBy=multi-user.target -``` - -Here's a simple install script that creates the boundary group and user, installs the -systemd unit file and enables it at startup: - -``` -#!/bin/bash -# Installs the boundary as a service for systemd on linux -# Usage: ./install.sh - -TYPE=$1 -NAME=boundary - -sudo cat << EOF > /etc/systemd/system/${NAME}-${TYPE}.service -[Unit] -Description=${NAME} ${TYPE} - -[Service] -ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl -User=boundary -Group=boundary -LimitMEMLOCK=infinity -Capabilities=CAP_IPC_LOCK+ep -CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK - -[Install] -WantedBy=multi-user.target -EOF - -# Add the boundary system user and group to ensure we have a no-login -# user capable of owning and running Boundary -sudo adduser --system --group boundary || true -sudo chown boundary:boundary /etc/${NAME}-${TYPE}.hcl -sudo chown boundary:boundary /usr/local/bin/boundary - -# Make sure to initialize the DB before starting the service. This will result in -# a database already initialized warning if another controller or worker has done this -# already, making it a lazy, best effort initialization -if [ "${TYPE}" = "controller" ]; then - sudo /usr/local/bin/boundary database init -config /etc/${NAME}-${TYPE}.hcl || true -fi - -sudo chmod 664 /etc/systemd/system/${NAME}-${TYPE}.service -sudo systemctl daemon-reload -sudo systemctl enable ${NAME}-${TYPE} -sudo systemctl start ${NAME}-${TYPE} -``` - -### Postgres Configuration - -TBD - -### KMS Configuration - -TBD diff --git a/website/content/docs/getting-started/connect-to-target.mdx b/website/content/docs/hcp/get-started/connect-to-target.mdx similarity index 99% rename from website/content/docs/getting-started/connect-to-target.mdx rename to website/content/docs/hcp/get-started/connect-to-target.mdx index 29e472723c..35164aeb47 100644 --- a/website/content/docs/getting-started/connect-to-target.mdx +++ b/website/content/docs/hcp/get-started/connect-to-target.mdx @@ -5,7 +5,7 @@ description: |- Connecting to your first target --- -# Connect to Your First Target +# Connect to your first target The [Quick setup wizard](/boundary/docs/getting-started/deploy-and-login#login-to-hcp-boundary) diff --git a/website/content/docs/getting-started/deploy-and-login.mdx b/website/content/docs/hcp/get-started/deploy-and-login.mdx similarity index 98% rename from website/content/docs/getting-started/deploy-and-login.mdx rename to website/content/docs/hcp/get-started/deploy-and-login.mdx index 1cdebffe96..5115ef54ea 100644 --- a/website/content/docs/getting-started/deploy-and-login.mdx +++ b/website/content/docs/hcp/get-started/deploy-and-login.mdx @@ -1,11 +1,11 @@ --- layout: docs -page_title: Deploy and Login +page_title: Deploy and log in description: |- - How to deploy HCP Boundary services and login for the first time. + How to deploy HCP Boundary services and log in for the first time. --- -# Deploy HCP Boundary and Login +# Deploy HCP Boundary and log in HCP Boundary provides secure access to remote hosts and infrastructure endpoints. Boundary enables secure connectivity to cloud service catalogs, diff --git a/website/content/docs/hcp/index.mdx b/website/content/docs/hcp/index.mdx new file mode 100644 index 0000000000..b92aef3d66 --- /dev/null +++ b/website/content/docs/hcp/index.mdx @@ -0,0 +1,17 @@ +--- +layout: docs +page_title: HCP Boundary +description: |- + An overview of HCP Boundary +--- + +# HCP Boundary + +HCP Boundary provides secure access to remote hosts and infrastructure endpoints. +Boundary enables secure connectivity to cloud service catalogs, on-premises infrastructure, and Kubernetes clusters without needing to manage any of the underlying systems or operations. + +HCP Boundary reduces the complexity of managing access to infrastructure, and enables the user to simply log in, select the desired host or system, and connect. +HCP Boundary handles the routing, connections, and credential brokering on the backend. +Users securely connect to their remote systems or hosts without exposing a credential, address, or network. + +To try out HCP Boundary, proceed to [Deploy and login](/boundary/docs/hcp/get-started/deploy-and-login). \ No newline at end of file diff --git a/website/content/docs/oss/installing/high-availability.mdx b/website/content/docs/install-boundary/high-availability.mdx similarity index 100% rename from website/content/docs/oss/installing/high-availability.mdx rename to website/content/docs/install-boundary/high-availability.mdx diff --git a/website/content/docs/oss/installing/index.mdx b/website/content/docs/install-boundary/index.mdx similarity index 100% rename from website/content/docs/oss/installing/index.mdx rename to website/content/docs/install-boundary/index.mdx diff --git a/website/content/docs/oss/installing/no-gen-resources.mdx b/website/content/docs/install-boundary/no-gen-resources.mdx similarity index 100% rename from website/content/docs/oss/installing/no-gen-resources.mdx rename to website/content/docs/install-boundary/no-gen-resources.mdx diff --git a/website/content/docs/oss/installing/postgres.mdx b/website/content/docs/install-boundary/postgres.mdx similarity index 100% rename from website/content/docs/oss/installing/postgres.mdx rename to website/content/docs/install-boundary/postgres.mdx diff --git a/website/content/docs/oss/installing/reference-architectures.mdx b/website/content/docs/install-boundary/reference-architectures.mdx similarity index 100% rename from website/content/docs/oss/installing/reference-architectures.mdx rename to website/content/docs/install-boundary/reference-architectures.mdx diff --git a/website/content/docs/oss/installing/systemd.mdx b/website/content/docs/install-boundary/systemd.mdx similarity index 100% rename from website/content/docs/oss/installing/systemd.mdx rename to website/content/docs/install-boundary/systemd.mdx diff --git a/website/content/docs/oss/operations/health.mdx b/website/content/docs/operations/health.mdx similarity index 96% rename from website/content/docs/oss/operations/health.mdx rename to website/content/docs/operations/health.mdx index d596a883e8..4442ffca31 100644 --- a/website/content/docs/oss/operations/health.mdx +++ b/website/content/docs/operations/health.mdx @@ -5,14 +5,14 @@ description: |- Verify the Boundary controller server is up and able to receive requests --- -## Boundary Health Endpoints +# Boundary Health Endpoints Boundary provides health monitoring through the `/health` path using a listener with the `"ops"` purpose. By default, a listener with that purpose runs on port `9203`. See the [example configuration](#example-configuration) section for an example listener stanza in a `config.hcl` file. -### Requirements +## Requirements To enable the controller health endpoint, any Boundary instance must be started with a controller. That is, a `controller` block and a `purpose = "api"` @@ -21,29 +21,29 @@ listener must be defined in Boundary's configuration file. Additionally, a file. Under these conditions, the `ops` server (which hosts the controller health api) will be exposed. -### Shutdown Grace Period +## Shutdown Grace Period Optionally, when the controller health endpoint is enabled, Boundary can be configured to change the controller health response to `503 Service Unavailable` upon receiving a shutdown signal, and wait a configurable amount of time before starting the shutdown process. - + This feature is designed to integrate with load balancers to reduce the risk of an outgoing Boundary instance causing disruption to incoming requests. - + In this state, Boundary is still capable of processing requests as normal, but will report as unhealthy through the controller health endpoint. In load-balanced environments, this would cause this "unhealthy" instance to be removed from the pool of instances eligible to handle requests, and thereby, reducing the likelihood that it will receive a request to handle during shutdown. - + This feature is disabled by default, even if the controller health endpoint is enabled. You can set it up by defining `graceful_shutdown_wait_duration` in the `controller` block of Boundary's configuration file. The value should be set to a string that is parseable by [ParseDuration](https://pkg.go.dev/time#ParseDuration). -### API +## API The new controller health service introduces a single read-only endpoint: @@ -55,7 +55,7 @@ The new controller health service introduces a single read-only endpoint: All responses return empty bodies. `GET /health` does not support any input. -## Example configuration +## Example configuration Health checks are available for a controller defined with a `purpose = "ops"` listener stanza. For details on what fields are allowed in this stanza, refer to diff --git a/website/content/docs/oss/operations/index.mdx b/website/content/docs/operations/index.mdx similarity index 97% rename from website/content/docs/oss/operations/index.mdx rename to website/content/docs/operations/index.mdx index 7ed65d7366..f933601ccf 100644 --- a/website/content/docs/oss/operations/index.mdx +++ b/website/content/docs/operations/index.mdx @@ -5,7 +5,7 @@ description: |- Operational tasks in Boundary. --- -# Maintaining and Operating Boundary +# Maintaining and operating Boundary Visibility into various components of Boundary plays an important role in ensuring the health of its controllers and workers. While additional monitoring diff --git a/website/content/docs/oss/operations/metrics.mdx b/website/content/docs/operations/metrics.mdx similarity index 96% rename from website/content/docs/oss/operations/metrics.mdx rename to website/content/docs/operations/metrics.mdx index d56265f3ee..bb75424b62 100644 --- a/website/content/docs/oss/operations/metrics.mdx +++ b/website/content/docs/operations/metrics.mdx @@ -5,7 +5,7 @@ description: |- Obtain visibility of various components of a running Boundary --- -## Boundary Metrics +# Boundary metrics Boundary provides metrics through the `/metrics` path using a listener with the `"ops"` purpose. By default, a listener with that purpose runs on port `9203`. @@ -22,7 +22,7 @@ exposition](https://prometheus.io/docs/instrumenting/exposition_formats/#openmet format which can be read by [Prometheus](https://prometheus.io/docs/introduction/overview/). -### Controller +## Controller The following table lists the current names and descriptions of metrics provided by controllers. @@ -34,7 +34,7 @@ by controllers. | `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. | -### Worker +## Worker The following table lists the current names and descriptions of metrics provided by workers. @@ -46,7 +46,7 @@ by workers. | `boundary_worker_proxy_websocket_received_bytes_total` | Count of received bytes sent over all proxy connections handled by the worker. | | `boundary_worker_proxy_websocket_sent_bytes_total` | Count of sent bytes sent over all proxy connections handled by the worker. | -### Other +## Other The following table lists the current miscellaneous metrics provided by Boundary. @@ -54,13 +54,13 @@ The following table lists the current miscellaneous metrics provided by Boundary |---------------------------------------------------------------|-----------------------------------------------| | `boundary_build_info` | A gauge set to 1 with label values detailing the current Go version, git revision, and Boundary version. | -### Metric Labels +## Metric labels Each metric uses labels to help organize and narrow its scope so that users can filter for different characteristics, allowing more flexible analysis of the measurements collected. -#### Metrics for HTTP requests include the following labels: +### Metrics for HTTP requests include the following labels: | Label | Description | |--------------|----------------------------------------------------------------| @@ -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 | |-----------------|-----------------------------------------------------------------| diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index e7b0d4f69a..7fbdc69c59 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -46,157 +46,65 @@ ] }, { - "title": "Getting Started", + "title": "Get Started", "routes": [ { "title": "Overview", "path": "getting-started" }, { - "title": "Installing", - "hidden": true, + "title": "Self-managed Boundary quick start", + "href": "https://developer.hashicorp.com/boundary/tutorials/oss-getting-started/" + }, + { + "title": "HCP Boundary quick start", + "href": "https://developer.hashicorp.com/boundary/tutorials/hcp-getting-started/" + }, + { + "title": "Dev Mode quick start", "routes": [ { - "title": "Overview", - "path": "getting-started/installing" + "title": "What is Dev Mode", + "path": "getting-started/dev-mode/dev-mode" + }, + { + "title": "Run and log in", + "path": "getting-started/dev-mode/run-and-login" }, { - "title": "Production", - "path": "getting-started/installing/production" + "title": "Connect to a target", + "path": "getting-started/dev-mode/connect-to-dev-target" } ] - }, - { - "title": "Deploy and Login", - "path": "getting-started/deploy-and-login" - }, - { - "title": "Connect to Target", - "path": "getting-started/connect-to-target" } ] }, { - "title": "Configuration", + "title": "Install Boundary", "routes": [ { - "title": "Overview/Top-Level Parameters", - "path": "configuration" + "title": "Overview", + "path": "install-boundary" }, { - "title": "worker", - "routes": [ - { - "title": "Overview", - "path": "configuration/worker" - }, - { - "title": "PKI Workers", - "path": "configuration/worker/pki-worker" - }, - { - "title": "KMS Workers", - "path": "configuration/worker/kms-worker", - "badge": { - "text": "OSS Only", - "type": "outlined", - "color": "neutral" - } - } - ] + "title": "Non-Dev Environments", + "path": "install-boundary/no-gen-resources" }, { - "title": "listener", - "routes": [ - { - "title": "Overview", - "path": "configuration/listener" - }, - { - "title": "TCP", - "path": "configuration/listener/tcp" - }, - { - "title": "Unix", - "path": "configuration/listener/unix" - } - ] + "title": "Systemd Install", + "path": "install-boundary/systemd" }, { - "title": "KMS", - "routes": [ - { - "title": "Overview", - "path": "configuration/kms" - }, - { - "title": "AEAD", - "path": "configuration/kms/aead" - }, - { - "title": "AWS KMS", - "path": "configuration/kms/awskms" - }, - { - "title": "AliCloud KMS", - "path": "configuration/kms/alicloudkms" - }, - { - "title": "Azure Key Vault", - "path": "configuration/kms/azurekeyvault" - }, - { - "title": "GCP Cloud KMS", - "path": "configuration/kms/gcpckms" - }, - { - "title": "OCI KMS", - "path": "configuration/kms/ocikms" - }, - { - "title": "Vault Transit", - "path": "configuration/kms/transit" - } - ] - }, - { - "title": "events", - "routes": [ - { - "title": "Overview", - "path": "configuration/events" - }, - { - "title": "Common Sink Parameters", - "path": "configuration/events/common" - }, - { - "title": "File Sink", - "path": "configuration/events/file" - }, - { - "title": "Stderr Sink", - "path": "configuration/events/stderr" - } - ] + "title": "Postgres Install", + "path": "install-boundary/postgres" }, { - "title": "controller", - "path": "configuration/controller", - "badge": { - "text": "OSS Only", - "type": "outlined", - "color": "neutral" - } + "title": "High Availability Install", + "path": "install-boundary/high-availability" }, { - "title": "plugins", - "path": "configuration/plugins", - "badge": { - "text": "OSS Only", - "type": "outlined", - "color": "neutral" - } + "title": "Reference Architectures", + "path": "install-boundary/reference-architectures" } ] }, @@ -353,6 +261,147 @@ } ] }, + { + "title": "Configuration", + "routes": [ + { + "title": "Overview/Top-Level Parameters", + "path": "configuration" + }, + { + "title": "worker", + "routes": [ + { + "title": "Overview", + "path": "configuration/worker" + }, + { + "title": "PKI Workers", + "path": "configuration/worker/pki-worker" + }, + { + "title": "KMS Workers", + "path": "configuration/worker/kms-worker", + "badge": { + "text": "OSS Only", + "type": "outlined", + "color": "neutral" + } + } + ] + }, + { + "title": "listener", + "routes": [ + { + "title": "Overview", + "path": "configuration/listener" + }, + { + "title": "TCP", + "path": "configuration/listener/tcp" + }, + { + "title": "Unix", + "path": "configuration/listener/unix" + } + ] + }, + { + "title": "KMS", + "routes": [ + { + "title": "Overview", + "path": "configuration/kms" + }, + { + "title": "AEAD", + "path": "configuration/kms/aead" + }, + { + "title": "AWS KMS", + "path": "configuration/kms/awskms" + }, + { + "title": "AliCloud KMS", + "path": "configuration/kms/alicloudkms" + }, + { + "title": "Azure Key Vault", + "path": "configuration/kms/azurekeyvault" + }, + { + "title": "GCP Cloud KMS", + "path": "configuration/kms/gcpckms" + }, + { + "title": "OCI KMS", + "path": "configuration/kms/ocikms" + }, + { + "title": "Vault Transit", + "path": "configuration/kms/transit" + } + ] + }, + { + "title": "events", + "routes": [ + { + "title": "Overview", + "path": "configuration/events" + }, + { + "title": "Common Sink Parameters", + "path": "configuration/events/common" + }, + { + "title": "File Sink", + "path": "configuration/events/file" + }, + { + "title": "Stderr Sink", + "path": "configuration/events/stderr" + } + ] + }, + { + "title": "controller", + "path": "configuration/controller", + "badge": { + "text": "OSS Only", + "type": "outlined", + "color": "neutral" + } + }, + { + "title": "plugins", + "path": "configuration/plugins", + "badge": { + "text": "OSS Only", + "type": "outlined", + "color": "neutral" + } + } + ] + }, + { + "title": "Operations", + "routes": [ + { + "title": "Overview", + "path": "operations" + }, + { + "title": "Metrics", + "path": "operations/metrics" + }, + { + "title": "Health Endpoint", + "path": "operations/health" + } + ] + }, { "title": "Troubleshoot", "routes": [ @@ -366,10 +415,6 @@ } ] }, - { - "title": "Common Workflows", - "href": "https://learn.hashicorp.com/boundary" - }, { "title": "Common Workflows", "hidden": true, @@ -434,103 +479,65 @@ } ] }, + { + "title": "Develop Boundary", + "routes": [ + { + "title": "Overview", + "path": "developing" + }, + { + "title": "Build Boundary", + "path": "developing/building" + }, + { + "title": "Develop the UI", + "path": "developing/ui" + } + ] + }, { "divider": true }, { "title": "Boundary OSS", + "hidden": true, "routes": [ { "title": "Overview", "path": "oss" - }, + } + ] + }, + { + "title": "HCP Boundary", + "routes": [ { - "title": "Installation", - "routes": [ - { - "title": "Overview", - "path": "oss/installing" - }, - { - "title": "Dev Mode", - "path": "oss/installing/dev-mode" - }, - { - "title": "Run and Login", - "path": "oss/installing/run-and-login" - }, - { - "title": "Connect to Dev Target", - "path": "oss/installing/connect-to-dev-target" - }, - { - "title": "Non-Dev Environments", - "path": "oss/installing/no-gen-resources" - }, - { - "title": "Systemd Install", - "path": "oss/installing/systemd" - }, - { - "title": "Postgres Install", - "path": "oss/installing/postgres" - }, - { - "title": "High Availability Install", - "path": "oss/installing/high-availability" - }, - { - "title": "Reference Architectures", - "path": "oss/installing/reference-architectures" - } - ] + "title": "Overview", + "path": "hcp" }, { - "title": "Operations", + "title": "Get started", "routes": [ { - "title": "Overview", - "path": "oss/operations" + "title": "Deploy and login", + "path": "hcp/get-started/deploy-and-login" }, { - "title": "Metrics", - "path": "oss/operations/metrics" - }, - { - "title": "Health Endpoint", - "path": "oss/operations/health" + "title": "Connect to target", + "path": "hcp/get-started/connect-to-target" } ] }, { - "title": "Developing Boundary", - "routes": [ - { - "title": "Overview", - "path": "oss/developing" - }, - { - "title": "Building", - "path": "oss/developing/building" - }, - { - "title": "Developing the UI", - "path": "oss/developing/ui" - } - ] + "title": "Documentation", + "href": "https://cloud.hashicorp.com/docs/boundary/" } ] }, { "divider": true }, - { - "title": "HCP Boundary", - "href": "https://cloud.hashicorp.com/docs/boundary/" - }, - { - "divider": true - }, { "title": "Release Notes", "routes": [ diff --git a/website/redirects.js b/website/redirects.js index ab745f0dc3..2b3b99e978 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -27,4 +27,100 @@ module.exports = [ destination: 'boundary/docs/overview/what-is-boundary', permanent: true, }, + { + source: '/boundary/docs/getting-started/connect-to-target', + destination: '/boundary/docs/hcp/get-started/connect-to-target', + permanent: true, + }, + { + source: '/boundary/docs/getting-started/deploy-and-login', + destination: '/boundary/docs/hcp/get-started/deploy-and-login', + permanent: true, + }, + { + source: '/boundary/docs/getting-started/installing', + destination: '/boundary/docs/getting-started', + permanent: true, + }, + { + source: '/boundary/docs/getting-started/installing/production', + destination: '/boundary/docs/getting-started', + permanent: true, + }, + { + source: '/boundary/docs/oss/developing/building', + destination: '/boundary/docs/developing/building', + permanent: true, + }, + { + source: '/boundary/docs/oss/developing', + destination: '/boundary/docs/developing', + permanent: true, + }, + { + source: '/boundary/docs/oss/developing/ui', + destination: '/boundary/docs/developing/ui', + permanent: true, + }, + { + source: '/boundary/docs/oss/installing/connect-to-dev-target', + destination: + '/boundary/docs/getting-started/dev-mode/connect-to-dev-target', + permanent: true, + }, + { + source: '/boundary/docs/oss/installing/dev-mode', + destination: '/boundary/docs/getting-started/dev-mode/dev-mode', + permanent: true, + }, + { + source: '/boundary/docs/oss/installing/run-and-login', + destination: '/boundary/docs/getting-started/dev-mode/run-and-login', + permanent: true, + }, + { + source: '/boundary/docs/oss/operations/health', + destination: '/boundary/docs/operations/health', + permanent: true, + }, + { + source: '/boundary/docs/oss/operations', + destination: '/boundary/docs/operations', + permanent: true, + }, + { + source: '/boundary/docs/oss/operations/metrics', + destination: '/boundary/docs/operations/metrics', + permanent: true, + }, + { + source: '/boundary/docs/oss/installing/high-availability', + destination: '/boundary/docs/install-boundary/high-availability', + permanent: true, + }, + { + source: '/boundary/docs/oss/installing', + destination: '/boundary/docs/install-boundary', + permanent: true, + }, + { + source: '/boundary/docs/oss/installing/no-gen-resources', + destination: '/boundary/docs/install-boundary/no-gen-resources', + permanent: true, + }, + { + source: '/boundary/docs/oss/installing/postgres', + destination: '/boundary/docs/install-boundary/postgres', + permanent: true, + }, + { + source: '/boundary/docs/oss/installing/reference-architectures', + destination: '/boundary/docs/install-boundary/reference-architectures', + permanent: true, + }, + { + source: '/boundary/docs/oss/installing/systemd', + destination: '/boundary/docs/install-boundary/systemd', + permanent: true, + }, ]