From 646a9cd8332523a121597ebbc567dad2fd524008 Mon Sep 17 00:00:00 2001 From: hc-github-team-secure-boundary <82989682+hc-github-team-secure-boundary@users.noreply.github.com> Date: Thu, 4 Apr 2024 11:13:17 -0700 Subject: [PATCH] doc: Refactor "install boundary" section (#4557) (#4597) * doc: Refactor "install boundary" section * CR: Use shell-session over bash * docs: Update redirects and TOC * CR: Word style/standards Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> * CR: Add second level heading * CR: Fix more shell-sessions * CR: Fix link --------- Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> (cherry picked from commit 82a6ac057d2d170c88bad9e5cfe26d28e515379b) Co-authored-by: Michael Li --- .../{ => architecture}/fault-tolerance.mdx | 0 .../{ => architecture}/high-availability.mdx | 0 .../recommended-architecture.mdx | 0 .../system-requirements.mdx | 0 .../configure-controllers.mdx | 19 ++-- .../{no-gen-resources.mdx => initialize.mdx} | 103 +++++++----------- website/data/docs-nav-data.json | 46 ++++---- website/redirects.js | 33 +++++- 8 files changed, 103 insertions(+), 98 deletions(-) rename website/content/docs/install-boundary/{ => architecture}/fault-tolerance.mdx (100%) rename website/content/docs/install-boundary/{ => architecture}/high-availability.mdx (100%) rename website/content/docs/install-boundary/{ => architecture}/recommended-architecture.mdx (100%) rename website/content/docs/install-boundary/{ => architecture}/system-requirements.mdx (100%) rename website/content/docs/install-boundary/{no-gen-resources.mdx => initialize.mdx} (70%) diff --git a/website/content/docs/install-boundary/fault-tolerance.mdx b/website/content/docs/install-boundary/architecture/fault-tolerance.mdx similarity index 100% rename from website/content/docs/install-boundary/fault-tolerance.mdx rename to website/content/docs/install-boundary/architecture/fault-tolerance.mdx diff --git a/website/content/docs/install-boundary/high-availability.mdx b/website/content/docs/install-boundary/architecture/high-availability.mdx similarity index 100% rename from website/content/docs/install-boundary/high-availability.mdx rename to website/content/docs/install-boundary/architecture/high-availability.mdx diff --git a/website/content/docs/install-boundary/recommended-architecture.mdx b/website/content/docs/install-boundary/architecture/recommended-architecture.mdx similarity index 100% rename from website/content/docs/install-boundary/recommended-architecture.mdx rename to website/content/docs/install-boundary/architecture/recommended-architecture.mdx diff --git a/website/content/docs/install-boundary/system-requirements.mdx b/website/content/docs/install-boundary/architecture/system-requirements.mdx similarity index 100% rename from website/content/docs/install-boundary/system-requirements.mdx rename to website/content/docs/install-boundary/architecture/system-requirements.mdx diff --git a/website/content/docs/install-boundary/configure-controllers.mdx b/website/content/docs/install-boundary/configure-controllers.mdx index 0bfed2d397..65814ae543 100644 --- a/website/content/docs/install-boundary/configure-controllers.mdx +++ b/website/content/docs/install-boundary/configure-controllers.mdx @@ -289,12 +289,15 @@ Refer to the documentation for additional [top-level configuration options](/bou Before you can start Boundary, you must initialize the database from one Boundary controller. This operation is only required once; it will execute the required database migrations for the Boundary cluster to operate. -The following command with the included flags creates initial resources in Boundary as an example. -For finer control over these resources, remvoe the flags. +```shell-session +boundary database init -config /etc/boundary.d/controller.hcl +``` -Run the following command to initialize the database: +Boundary automatically generates a number of resources to make getting started easier. Default scopes, auth methods, +user, account, and targets are some of the resources Boundary automatically generates unless you configure it not to. These +resources, however, are not required. You can add the following flags to skip creating these initial resources: -```hcl +```shell-session boundary database init \ -skip-auth-method-creation \ -skip-host-resources-creation \ @@ -303,9 +306,9 @@ boundary database init \ -config /etc/boundary.d/controller.hcl ``` -You can use the help output for the `init` command to view the flags available to skip the creation of any auto-generated resources: +Use the following command to view the help for additional options: -```hcl +```shell-session boundary database init -h ``` @@ -322,5 +325,5 @@ Run the following commands to start the service: Upon logging in to Boundary for the first time, HashiCorp recommends creating an admin user for the global and project level scopes to manage Boundary. This allows you to configure targets within those scopes and manage them. -We recommend that you use the [KMS recovery workflow](/boundary/docs/install-boundary/no-gen-resources#recovery-kms-workflow) to log in to Boundary for the first time. -Refer to [Creating your first login account](/boundary/docs/install-boundary/no-gen-resources/#creating-your-first-login-account) to learn about setting up your first auth method, user, account, and role to log in to Boundary going forward without the recovery KMS workflow. +HashiCorp recommends that you use the [KMS recovery workflow](/boundary/docs/install-boundary/initialize#log-in-with-recovery-kms) to log in to Boundary for the first time. +Refer to [Creating your first login account](/boundary/docs/install-boundary/initialize#create-your-first-login-account) to learn about setting up your first auth method, user, account, and role to log in to Boundary going forward without the recovery KMS workflow. diff --git a/website/content/docs/install-boundary/no-gen-resources.mdx b/website/content/docs/install-boundary/initialize.mdx similarity index 70% rename from website/content/docs/install-boundary/no-gen-resources.mdx rename to website/content/docs/install-boundary/initialize.mdx index b390865182..b333efd843 100644 --- a/website/content/docs/install-boundary/no-gen-resources.mdx +++ b/website/content/docs/install-boundary/initialize.mdx @@ -1,25 +1,30 @@ --- layout: docs -page_title: Running Boundary in non-dev environments +page_title: Initialize Boundary description: |- - How to install boundary in non-dev environments. + Creating your first login account --- -# Install Boundary without generated resources +# Initialize Boundary -What are generated resources? When you run `boundary dev` or `boundary database init`, Boundary automatically -generates a number of resources to make getting started easier. Default scopes, auth methods, user, account, and -targets are just some of the resources Boundary will generate unless you tell it not to. +This document describes how to access Boundary for the first time and create the necessary resources to log in as a +user. -In a production or long-running environment, these resources are not necessary, but without them, managing -Boundary from scratch isn't straight forward. How do you create your first user and login to administer a Boundary -deployment that has no authentication methods, users, accounts, etc.? This section describes how to get your freshly -deployed Boundary installation off the ground for non-dev environments. +## Requirements -## Recovery KMS workflow +Before you initialize Boundary, you should have [initialized a database](/boundary/docs/install-boundary/configure-controllers#initialize-the-database). -Initializing Boundary without generated resources starts with your Boundary configuration file. Specifically, -the controller configuration specifies three KMS blocks: +## Log in with recovery KMS + +To access a new Boundary instance for the first time, you must use the recovery KMS defined in the +controller configuration file. The following example represents a configuration file that uses hard-coded AEAD keys: + + + +In a production environment, HashiCorp recommends that you use a cloud provider's KMS such as [AWS KMS](/boundary/docs/configuration/kms/awskms) +to manage the keys Boundary uses to encrypt sensitive information. + + ```hcl @@ -46,14 +51,9 @@ kms "aead" { ``` -In this example, we're using hardcoded AEAD keys, but in a real world non-dev deployment, you -should use your cloud provider's KMS such as [AWS KMS](/boundary/docs/configuration/kms/awskms) to manage the keys Boundary -uses to encrypt sensitive information. - -The KMS block we're focused on is the `recovery` block. This block specifies the key used to "recover" Boundary -but you can also use it to authenticate to Boundary and manage it as a "global" super user. This allows -you to authenticate from the CLI or from Terraform in order to manage Boundary without any generated -resources. +The KMS with the `recovery` purpose is used to "recover" Boundary, allowing you to authenticate to Boundary and manage +it as a super user. It also allows you to authenticate from the CLI or from Terraform to manage Boundary +without any generated resources. To authenticate to Boundary using the recovery KMS workflow: @@ -63,9 +63,9 @@ To authenticate to Boundary using the recovery KMS workflow: To use the recovery workflow on the CLI, you must pass the `-recovery-config ` flag or set the environment variable for `BOUNDARY_RECOVERY_CONFIG` for every command ran. Authentication takes place for every command -ran when using the recovery workflow, there is no `boundary authenticate` step: +ran when using the recovery workflow. The `boundary authenticate` command does not apply when you use the recovery KMS. -```bash +```shell-session $ cat << EOF > /tmp/recovery.hcl kms "aead" { purpose = "recovery" @@ -75,6 +75,7 @@ kms "aead" { } EOF +# Example command $ boundary users create -recovery-config /tmp/recovery.hcl ... ``` @@ -103,50 +104,22 @@ EOT - -## Initialize the database - -Before you can start Boundary, the database must be initialized. It's useful to look at the help output for the init command: - -``` -$ boundary database init -h -... -``` - -From this command, you can see the flags available to skip the creation of auto-generated resources. - -To initialize the Boundary database without generated resources: - -``` -$ boundary database init \ - -skip-auth-method-creation \ - -skip-host-resources-creation \ - -skip-scopes-creation \ - -skip-target-creation \ - -config /etc/boundary.hcl -``` - -When you start Boundary, you will effectively have a blank sheet to work against. The initial migrations in the database have been run (note that this includes creating special users like `u_anon` and the `global` scope) and the internal keyrings have been initialized. From here, it's required that -you use the KMS recovery workflow described above to create at a minimum an auth method, a user, an account, and a -role with sufficient grants. Otherwise, you need to continue to use the recovery workflow for management. It's important -to realize that this is effectively a global super user type of workflow and comes with security concerns. - ## Create your first login account -This section covers how to configure your first auth method, user, account, and role to login to Boundary without -the recovery KMS workflow. In this example, we're going to make an admin user for the global and project level +This section covers how to configure your first auth method, user, account, and role to log in to Boundary without +the recovery KMS workflow. In this example, we are going to make an admin user for the global and project level scopes we create. This will allow our user to configure targets within those scopes and manage them. ### Create org and project scopes -In this example, we're going to create an org and project scope and skip creating an administrator and admin role -for each scope. We're going to specify a role for managing these scopes by selected users in a later step. +First, create an org and project scope and skip creating an administrator and admin role for each scope. We are going to +specify a role for managing these scopes by selected users in a later step. -```bash +```shell-session $ boundary scopes create -name 'org' -scope-id 'global' \ -recovery-config /tmp/recovery.hcl \ -skip-admin-role-creation \ @@ -195,7 +168,7 @@ Create an auth method in the organization scope. -```bash +```shell-session $ boundary auth-methods create password \ -recovery-config /tmp/recovery.hcl \ -scope-id \ @@ -228,7 +201,7 @@ Create a login account for the auth method. -```bash +```shell-session $ boundary accounts create password \ -recovery-config /tmp/recovery.hcl \ -login-name "myuser" \ @@ -263,7 +236,7 @@ This user will also be the principal in the role we create in the following step -```bash +```shell-session $ boundary users create -scope-id \ -recovery-config /tmp/recovery.hcl \ -name "myuser" \ @@ -294,8 +267,8 @@ resource "boundary_user" "myuser" { ### Create roles to manage scopes -The following describes the four baseline roles you'll need to create to manage resources within the org and project -scopes created above. These roles are similar to the roles created for you if generation had not been skipped during `boundary database init` when executed with the `-skip-initial-login-role-creation` flag, Declaring roles explicitly +The following section describes the four baseline roles you must create to manage resources within the org and project +scopes that you created. These roles are similar to the roles Boundary automatically created for you if you did not skip generation using the `-skip-initial-login-role-creation` flag when you ran `boundary database init`. Declaring roles explicitly allows you to manage them independently and fully within Terraform or via the CLI. In doing so, you can precisely define their access. The following example creates 4 roles: @@ -313,7 +286,7 @@ The following example creates 4 roles: Assumes recovery key export from above steps is still set: -```bash +```shell-session # Create global anonymous listing role $ boundary roles create -name 'global_anon_listing' \ -recovery-config /tmp/recovery.hcl \ @@ -358,7 +331,7 @@ resource "boundary_role" "global_anon_listing" { Assumes recovery key export from above steps is still set: -```bash +```shell-session $ boundary roles create -name 'org_anon_listing' \ -recovery-config /tmp/recovery.hcl \ -scope-id @@ -402,7 +375,7 @@ resource "boundary_role" "org_anon_listing" { Assumes recovery key export from above steps is still set: -```bash +```shell-session $ boundary roles create -name 'org_admin' \ -recovery-config /tmp/recovery.hcl \ -scope-id 'global' \ @@ -444,7 +417,7 @@ resource "boundary_role" "org_admin" { Assumes recovery key export from above steps is still set: -```bash +```shell-session $ boundary roles create -name 'project_admin' \ -recovery-config /tmp/recovery.hcl \ -scope-id \ diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index c1aff63369..d5708a021b 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -52,14 +52,14 @@ "title": "Overview", "path": "getting-started" }, - { - "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": "Self-managed Boundary quick start", + "href": "https://developer.hashicorp.com/boundary/tutorials/oss-getting-started/" + }, { "title": "Dev mode quick start", "routes": [ @@ -87,16 +87,25 @@ "path": "install-boundary" }, { - "title": "Recommended architecture", - "path": "install-boundary/recommended-architecture" - }, - { - "title": "System requirements", - "path": "install-boundary/system-requirements" - }, - { - "title": "Fault tolerance recommendations", - "path": "install-boundary/fault-tolerance" + "title": "Architecture", + "routes": [ + { + "title":"System requirements", + "path": "install-boundary/architecture/system-requirements" + }, + { + "title": "Recommended architecture", + "path": "install-boundary/architecture/recommended-architecture" + }, + { + "title": "Fault tolerance", + "path": "install-boundary/architecture/fault-tolerance" + }, + { + "title": "High availability", + "path": "install-boundary/architecture/high-availability" + } + ] }, { "title": "Install Boundary", @@ -111,17 +120,13 @@ "path": "install-boundary/configure-workers" }, { - "title": "Non-dev environments", - "path": "install-boundary/no-gen-resources" + "title": "Initialize Boundary", + "path": "install-boundary/initialize" }, { "title": "Systemd install", "hidden": true, "path": "install-boundary/systemd" - }, - { - "title": "Configure high availability", - "path": "install-boundary/high-availability" } ] }, @@ -1515,7 +1520,6 @@ } ] }, - { "title": "Develop Boundary", "routes": [ diff --git a/website/redirects.js b/website/redirects.js index 954a05ae44..0bdcf75be5 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -93,9 +93,19 @@ module.exports = [ destination: '/boundary/docs/operations/metrics', permanent: true, }, + { + source: '/boundary/docs/install-boundary/fault-tolerance', + destination: '/boundary/docs/install-boundary/architecture/fault-tolerance', + permanent: true, + }, { source: '/boundary/docs/oss/installing/high-availability', - destination: '/boundary/docs/install-boundary/high-availability', + destination: '/boundary/docs/install-boundary/architecture/high-availability', + permanent: true, + }, + { + source: '/boundary/docs/install-boundary/high-availability', + destination: '/boundary/docs/install-boundary/architecture/high-availability', permanent: true, }, { @@ -108,19 +118,34 @@ module.exports = [ destination: '/boundary/docs/install-boundary/no-gen-resources', permanent: true, }, + { + source: '/boundary/docs/install-boundary/no-gen-resources', + destination: '/boundary/docs/install-boundary/initialize', + permanent: true, + }, { source: '/boundary/docs/oss/installing/postgres', - destination: '/boundary/docs/install-boundary/system-requirements', + destination: '/boundary/docs/install-boundary/architecture/system-requirements', permanent: true, }, { source: '/boundary/docs/install-boundary/postgres', - destination: '/boundary/docs/install-boundary/system-requirements', + destination: '/boundary/docs/install-boundary/architecture/system-requirements', + permanent: true, + }, + { + source: '/boundary/docs/install-boundary/system-requirements', + destination: '/boundary/docs/install-boundary/architecture/system-requirements', permanent: true, }, { source: '/boundary/docs/oss/installing/reference-architectures', - destination: '/boundary/docs/install-boundary/recommended-architecture', + destination: '/boundary/docs/install-boundary/architecture/recommended-architecture', + permanent: true, + }, + { + source: '/boundary/docs/install-boundary/recommended-architecture', + destination: 'boundary/docs/install-boundary/architecture/recommended-architecture', permanent: true, }, {