doc: Refactor "install boundary" section (#4557)
* 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>
This commit is contained in:
Michael LiandDan Heath authored and 
GitHub committed
1 parent
1e5559173f
commit
82a6ac057d
8 files changed
+103
-98
No files matched your search
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -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.
|
||||
+38
-65
@@ -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:
|
||||
|
||||
<Note>
|
||||
|
||||
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.
|
||||
|
||||
</Note>
|
||||
|
||||
```hcl
|
||||
<truncated>
|
||||
@@ -46,14 +51,9 @@ kms "aead" {
|
||||
<truncated>
|
||||
```
|
||||
|
||||
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 <path_to_kms_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 <truncated> -recovery-config /tmp/recovery.hcl
|
||||
...
|
||||
```
|
||||
@@ -103,50 +104,22 @@ EOT
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
```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.
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
```bash
|
||||
```shell-session
|
||||
$ boundary auth-methods create password \
|
||||
-recovery-config /tmp/recovery.hcl \
|
||||
-scope-id <org_scope_id> \
|
||||
@@ -228,7 +201,7 @@ Create a login account for the auth method.
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
```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
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
```bash
|
||||
```shell-session
|
||||
$ boundary users create -scope-id <org_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 <org_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 <org_scope_id> \
|
||||
@@ -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": [
|
||||
|
||||
+29
-4
@@ -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,
|
||||
},
|
||||
{
|
||||
|
||||
Reference in new issue
Block a user