mirror of https://github.com/hashicorp/boundary
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
488 lines
12 KiB
488 lines
12 KiB
---
|
|
layout: docs
|
|
page_title: Running Boundary in Non-Dev Environments
|
|
description: |-
|
|
How to install boundary in non-dev environments.
|
|
---
|
|
|
|
# Installing Boundary Without Generated Resources
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Recovery KMS Workflow
|
|
|
|
Initializing Boundary without generated resources starts with your Boundary configuration file. Specifically,
|
|
the controller configuration specifies three KMS blocks:
|
|
|
|
```hcl
|
|
<truncated>
|
|
kms "aead" {
|
|
purpose = "root"
|
|
aead_type = "aes-gcm"
|
|
key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="
|
|
key_id = "global_root"
|
|
}
|
|
|
|
kms "aead" {
|
|
purpose = "worker-auth"
|
|
aead_type = "aes-gcm"
|
|
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
|
key_id = "global_worker-auth"
|
|
}
|
|
|
|
kms "aead" {
|
|
purpose = "recovery"
|
|
aead_type = "aes-gcm"
|
|
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
|
key_id = "global_recovery"
|
|
}
|
|
<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](/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.
|
|
|
|
To authenticate to Boundary using the recovery KMS workflow:
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
|
|
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:
|
|
|
|
```bash
|
|
$ cat << EOF > /tmp/recovery.hcl
|
|
kms "aead" {
|
|
purpose = "recovery"
|
|
aead_type = "aes-gcm"
|
|
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
|
key_id = "global_recovery"
|
|
}
|
|
EOF
|
|
|
|
$ boundary users create <truncated> -recovery-config /tmp/recovery.hcl
|
|
...
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Terraform">
|
|
|
|
|
|
To configure your provider to use the recovery KMS workflow, provide the KMS block as the value for
|
|
`recovery_kms_hcl`:
|
|
|
|
```hcl
|
|
provider "boundary" {
|
|
addr = 'https://boundary.mycorp.com:9200'
|
|
recovery_kms_hcl = <<EOT
|
|
kms "aead" {
|
|
purpose = "recovery"
|
|
aead_type = "aes-gcm"
|
|
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
|
key_id = "global_recovery"
|
|
}
|
|
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.
|
|
|
|
## Creating 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
|
|
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.
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
|
|
```bash
|
|
$ boundary scopes create -name 'org' -scope-id 'global' \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-skip-admin-role-creation \
|
|
-skip-default-role-creation
|
|
<truncated>
|
|
|
|
$ boundary scopes create -name 'project' -scope-id <org_scope_id_from_last_step> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-skip-admin-role-creation \
|
|
-skip-default-role-creation
|
|
<truncated>
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Terraform">
|
|
|
|
|
|
```hcl
|
|
resource "boundary_scope" "org" {
|
|
scope_id = "global"
|
|
name = "organization"
|
|
description = "Organization scope"
|
|
|
|
auto_create_admin_role = false
|
|
auto_create_default_role = false
|
|
}
|
|
|
|
resource "boundary_scope" "project" {
|
|
name = "project"
|
|
description = "My first project"
|
|
scope_id = boundary_scope.org.id
|
|
auto_create_admin_role = false
|
|
auto_create_default_role = false
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
### Create an Auth Method
|
|
|
|
Create an auth method in the organization scope.
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
|
|
```bash
|
|
$ boundary auth-methods create password \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-scope-id <org_scope_id> \
|
|
-name 'my_method' \
|
|
-description 'My password auth method'
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Terraform">
|
|
|
|
|
|
```hcl
|
|
resource "boundary_auth_method" "password" {
|
|
name = "my_password_auth_method"
|
|
description = "Password auth method"
|
|
type = "password"
|
|
scope_id = boundary_scope.org.id
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
### Create a Login Account
|
|
|
|
Create a login account for the auth method.
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
|
|
```bash
|
|
$ boundary accounts create password \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-login-name "myuser" \
|
|
-auth-method-id <auth_method_id_from_last_step>
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Terraform">
|
|
|
|
|
|
```hcl
|
|
resource "boundary_account" "myuser" {
|
|
name = "myuser"
|
|
description = "User account for my user"
|
|
type = "password"
|
|
login_name = "myuser"
|
|
password = "foofoofoo"
|
|
auth_method_id = boundary_auth_method.password.id
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
### Create a User
|
|
|
|
Create a user and associate the user with the login account created in the previous step.
|
|
This user will also be the principal in the role we create in the following step.
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
|
|
```bash
|
|
$ boundary users create -scope-id <org_scope_id> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-name "myuser" \
|
|
-description "My user!"
|
|
|
|
$ boundary users add-accounts \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-id <myuser_user_id> \
|
|
-account <myuser_account_id>
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Terraform">
|
|
|
|
|
|
```hcl
|
|
resource "boundary_user" "myuser" {
|
|
name = "myuser"
|
|
description = "My user!"
|
|
account_ids = [boundary_account.myuser.id]
|
|
scope_id = boundary_scope.org.id
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
### 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
|
|
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:
|
|
|
|
1. To allow anonymous (unauthenticated) users the ability to list scopes and auth methods in the global scope.
|
|
1. To allow anonymous (unauthenticated) users the ability to list scopes and auth methods in the organization scope.
|
|
1. To allow `myuser` user administration grants at the org scope.
|
|
1. To allow `myuser` user administration grants at the project scope.
|
|
|
|
#### Anonymous listing role for global scope
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
|
|
Assumes recovery key export from above steps is still set:
|
|
|
|
```bash
|
|
# Create global anonymous listing role
|
|
$ boundary roles create -name 'global_anon_listing' \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-scope-id 'global'
|
|
|
|
$ boundary roles add-grants -id <global_anon_listing_id> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-grant 'id=*;type=auth-method;actions=list,authenticate' \
|
|
-grant 'id=*;type=scope;actions=list,no-op' \
|
|
-grant 'id={{account.id}};actions=read,change-password'
|
|
|
|
$ boundary roles add-principals -id <global_anon_listing_id> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-principal 'u_anon'
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Terraform">
|
|
|
|
|
|
```hcl
|
|
resource "boundary_role" "global_anon_listing" {
|
|
scope_id = "global"
|
|
grant_strings = [
|
|
"id=*;type=auth-method;actions=list,authenticate",
|
|
"id=*;type=scope;actions=list,no-op",
|
|
"id={{account.id}};actions=read,change-password"
|
|
]
|
|
principal_ids = ["u_anon"]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
#### Anonymous listing role for org scope
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
|
|
Assumes recovery key export from above steps is still set:
|
|
|
|
```bash
|
|
$ boundary roles create -name 'org_anon_listing' \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-scope-id <org_scope_id>
|
|
|
|
$ boundary roles add-grants -id <org_anon_listing_id> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-grant 'id=*;type=auth-method;actions=list,authenticate' \
|
|
-grant 'type=scope;actions=list' \
|
|
-grant 'id={{account.id}};actions=read,change-password'
|
|
|
|
$ boundary roles add-principals -id <org_anon_listing_id> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-principal 'u_anon'
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Terraform">
|
|
|
|
|
|
```hcl
|
|
resource "boundary_role" "org_anon_listing" {
|
|
scope_id = boundary_scope.org.id
|
|
grant_strings = [
|
|
"id=*;type=auth-method;actions=list,authenticate",
|
|
"type=scope;actions=list",
|
|
"id={{account.id}};actions=read,change-password"
|
|
]
|
|
principal_ids = ["u_anon"]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
#### Org admin role for myuser
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
|
|
Assumes recovery key export from above steps is still set:
|
|
|
|
```bash
|
|
$ boundary roles create -name 'org_admin' \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-scope-id 'global' \
|
|
-grant-scope-id <org_scope_id>
|
|
|
|
$ boundary roles add-grants -id <org_admin_id> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-grant 'id=*;type=*;actions=*'
|
|
|
|
$ boundary roles add-principals -id <org_admin_id> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-principal <myuser_user_id>
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Terraform">
|
|
|
|
|
|
```hcl
|
|
resource "boundary_role" "org_admin" {
|
|
scope_id = "global"
|
|
grant_scope_id = boundary_scope.org.id
|
|
grant_strings = [
|
|
"id=*;type=*;actions=*"
|
|
]
|
|
principal_ids = [boundary_user.myuser.id]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
#### Project admin for myuser
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
|
|
Assumes recovery key export from above steps is still set:
|
|
|
|
```bash
|
|
$ boundary roles create -name 'project_admin' \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-scope-id <org_scope_id> \
|
|
-grant-scope-id <project_scope_id>
|
|
|
|
$ boundary roles add-grants -id <project_admin_id> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-grant 'id=*;type=*;actions=*'
|
|
|
|
$ boundary roles add-principals -id <project_admin_id> \
|
|
-recovery-config /tmp/recovery.hcl \
|
|
-principal <myuser_user_id>
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Terraform">
|
|
|
|
|
|
```hcl
|
|
resource "boundary_role" "project_admin" {
|
|
scope_id = boundary_scope.org.id
|
|
grant_scope_id = boundary_scope.project.id
|
|
grant_strings = [
|
|
"id=*;type=*;actions=*"
|
|
]
|
|
principal_ids = [boundary_user.myuser.id]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
### Login as Your New User
|
|
|
|
```bash
|
|
boundary authenticate password \
|
|
-auth-method-id <auth_method_id> \
|
|
-login-name myuser
|
|
```
|