Configure controllers
Refer to the sections below to configure your Boundary controllers.
Prepare TLS certificates
HashiCorp recommends that the Boundary controller nodes handle TLS via PKI for user connections. Further, we strongly recommend that you use certificates that are generated and signed by an appropriate certificate authority (CA).
To use TLS, you must have two files on each Boundary controller node.
You may have to create a new directory to store the certificate material at /etc/boundary.d/tls
.
Place the files in the following paths:
/etc/boundary.d/tls/boundary-cert.pem
In this path, place the Boundary TLS certificate with a Common Name (CN) and Subject Alternate Name (SAN) that matches your planned primary DNS record for accessing the Boundary controllers and any additional SANs as necessary.
/etc/boundary.d/tls/boundary-key.pem
In this path, place the Boundary TLS certificate's private key.
If you do not generate unique TLS key material for each node, you should securely distribute the key material to each of the Boundary controller nodes.
Prepare KMS keys
Boundary controllers require the two following different cryptographic keys:
- Root key: The root KMS key acts as a KEK (Key Encrypting Key) for the scope-specific KEKs (also referred to as the scope's root key). The scope's root KEK and the various DEKs (Data Encryption Keys) are created when a scope is created. The DEKs are encrypted with the scope's root KEK, and this is in turn encrypted with the KMS key marked for the root purpose.
- Recovery key: The recovery KMS key is used for rescue or recovery operations that can be used by a client to authenticate almost any Boundary operation. A nonce and creation time are included as an encrypted payload, formatted as a token, and sent to the controller. The time and nonce are used to ensure that a value cannot be replayed by an adversary, and also to ensure that each operation must be individually authenticated by a client, so that revoking access to the KMS has an immediate result.
The following key is optional:
- Worker-auth key (Optional): The worker-auth KMS key is shared by the controller and worker to authenticate a worker to the controller. If a worker is used with PKI authentication, this is unnecessary.
There are other optional KMS keys that you can configure for different encryption scenarios. These scenarios include Boundary worker PKI auth encryption and Boundary worker or controller configuration encryption. Refer to Data security in Boundary for more information.
Note
There are two types of Boundary workers, distinguished by the method by which they authenticate with the Boundary controllers. One worker uses a PKI exchange to authenticate with the controllers, and the other uses a KMS key that can be used for authentication by both the worker and the controller. You use the Worker-auth key listed above to enable KMS worker authentication.HashiCorp strongly recommends that you use either Vault Transit or your cloud provider's key management system. Refer to the Vault Transit documentation or your cloud provider's key management documentation for more information.
After you create the keys in Vault or the key management system of your choice, you can prepare the PostgreSQL database.
Prepare the database
Boundary manages its state and configuration in a Relational Database Management System (RDBMS), PostgreSQL. You should create, set up, and make the PostgreSQL database accessible to the Boundary controller nodes before you configure the nodes.
Refer to the Database recommendations documentation for examples of cloud managed PostgreSQL databases.
Create the controller configuration
Once you have configured the following, you can create the controller configuration:
- At least three virtual machines with Boundary installed on them
- At least one TLS certificate and key to distribute to the virtual machines for TLS communication
- KMS keys to use for at least root and recovery operations
- A PostgreSQL database to manage configuration and state
You must complete the following controller configuration for each of the Boundary controller nodes.
Base controller configuration
The core required values for a Boundary controller configuration include the following:
listener
blocks forapi
,cluster
, andops
- A
kms
block disable_mlock
- A
controller
block
When you install Boundary from the HashiCorp Linux Repository, it installs some example configuration files under /etc/boundary.d/
.
Run the following commands to rename the example configuration files:
sudo mv boundary.hcl boundary.hcl.old
sudo mv controller.hcl controller.hcl.old
sudo mv worker.hcl worker.hcl.old
We recommend that you use either the env://
or file://
notation in the configuration files to securely provide secret configuration components to the Boundary controller binaries.
In the following controller configuration example, we use env://
to declare the PostgreSQL connection string, as well as secure the AWS KMS configuration items.
When you install the Boundary binary using a package manager, it includes a unit file that configures an environment file at /etc/boundary.d/boundary.env
.
You can use this file to set the sensitive values that are used to configure the Boundary controllers and workers.
The following is an example of how this environment file could be configured:
123
Note
In the example above, the proper IAM roles and permissions for the given AWS_ACCESS_KEY
and AWS_SECRET_ACCESS_KEY
must be in place so that Boundary can use them to access the different KMS keys.
Next, populate the controller.hcl
file with any relevant configuration information.
The following example configuration file is a good starting point for a production Boundary controller installation.
It defines the three listener
blocks, two unique kms
blocks that are specific to AWS (as an example), the disable_mlock
value, and the controller
block.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100101102103104105106107108109110111112113114115116117118119120121122123
Refer to the list below for explanations of the parameters used in the example above:
disable mlock (bool: false)
- Disables the server from executing themlock
syscall, which prevents memory from being swapped to the disk. This is fine for local development and testing. However, it is not recommended for production unless the systems running Boundary use only encrypted swap or do not use swap at all. Boundary only supports memory locking on UNIX-like systems that supportmlock()
syscall like Linux and FreeBSD.On Linux, to give the Boundary executable the ability to use
mlock
syscall without running the process as root, run the following command:sudo setcap cap_ipc_lock=+ep $(readlink -f $(which boundary))
If you use a Linux distribution with a modern version of systemd, you can add the following directive to the "[Service]" configuration section:
LimitMEMLOCK=infinity
listener
- Configures the listeners on which Boundary serves traffic (API cluster and proxy).controller
- Configures the controller. If present,boundary server
starts a controller subprocess.events
- Configures event-specific parameters.The example events configuration above is exhaustive and writes all events to both
stderr
and a file. This configuration may or may not work for your organization's logging solution.kms
- Configures KMS blocks for various purposes.Refer to the links below for configuration information for the different cloud KMS blocks:
Refer to the documentation for additional top-level configuration options and additional controller-specific options.
Initialize the database
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.
Run the following command to initialize the database:
You can use the help output for the init
command to view the flags available to skip the creation of any auto-generated resources:
Start the Boundary service
When the configuration files are in place on each Boundary controller, you can proceed to enable and start the binary on each of the Boundary controller nodes using systemd
.
Run the following commands to start the service:
Authenticate and manage resources
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 to log in to Boundary for the first time. Refer to 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.