HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Boundary
Boundary Home

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 keys are 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.
  • BSR key (Optional): The BSR KMS key is required for session recording. Boundary uses the BSR key for encrypting data and checking the integrity of recordings. If you do not add a BSR key to your controller configuration, you receive an error when you attempt to enable session recording.

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:

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:

  1. sudo mv boundary.hcl boundary.hcl.old
  2. sudo mv controller.hcl controller.hcl.old
  3. 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:

/etc/boundary.d/boundary.env

POSTGRESQL_CONNECTION_STRING=postgresql://boundary:boundary@postgres.yourdomain.com:5432/boundary
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

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.

/etc/boundary.d/controller.hcl

# disable memory from being swapped to disk
disable_mlock = true

# API listener configuration block
listener "tcp" {
  # Should be the address of the NIC that the controller server will be reached on
  # Use 0.0.0.0 to listen on all interfaces
  address = "0.0.0.0:9200"
  # The purpose of this listener block
  purpose = "api"

  # TLS Configuration
  tls_disable   = false
  tls_cert_file = "/etc/boundary.d/tls/boundary-cert.pem"
  tls_key_file  = "/etc/boundary.d/tls/boundary-key.pem"

  # Uncomment to enable CORS for the Admin UI. Be sure to set the allowed origin(s)
  # to appropriate values.
  #cors_enabled = true
  #cors_allowed_origins = ["https://yourcorp.yourdomain.com", "serve://boundary"]
}

# 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 = "0.0.0.0:9201"
  # The purpose of this listener
  purpose = "cluster"
}

# Ops listener for operations like health checks for load balancers
listener "tcp" {
  # Should be the address of the interface where your external systems'
  # (eg: Load-Balancer and metrics collectors) will connect on.
  address = "0.0.0.0:9203"
  # The purpose of this listener block
  purpose = "ops"

  tls_disable   = false
  tls_cert_file = "/etc/boundary.d/tls/boundary-cert.pem"
  tls_key_file  = "/etc/boundary.d/tls/boundary-key.pem"
}

# Controller configuration block
controller {
  # This name attr must be unique across all controller instances if running in HA mode
  name = "boundary-controller-1"
  description = "Boundary controller number one"

  # This is the public hostname or IP where the workers can reach the
  # controller. This should typically be a load balancer address
  public_cluster_addr = "example-cluster-lb.example.com"

  # Enterprise license file, can also be the raw value or env:// value
  license = "file:///path/to/license/file.hclic"

  # After receiving a shutdown signal, Boundary will wait 10s before initiating the shutdown process.
  graceful_shutdown_wait_duration = "10s"

  # Database URL for postgres. This is set in boundary.env and
  #consumed via the “env://” notation.
  database {
      url = "env://POSTGRESQL_CONNECTION_STRING"
  }
}

# Events (logging) configuration. This
# configures logging for ALL events to both
# stderr and a file at /var/log/boundary/controller.log
events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enable = true
  sink "stderr" {
    name = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format = "cloudevents-json"
  }
  sink {
    name = "file-sink"
    description = "All events sent to a file"
    event_types = ["*"]
    format = "cloudevents-json"
    file {
      path = "/var/log/boundary"
      file_name = "controller.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# Root KMS Key (managed by AWS KMS in this example)
# Keep in mind that sensitive values are provided via ENV VARS
# in this example, such as access_key and secret_key
kms "awskms" {
  purpose    = "root"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

# Recovery KMS Key
kms "awskms" {
  purpose    = "recovery"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey2"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

# Worker-Auth KMS Key (optional, only needed if you use
# KMS authenticated workers)
kms "awskms" {
  purpose    = "worker-auth"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey3"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

# BSR KMS Key (optional, only needed if you use the
# session recording feature)
kms "awskms" {
  purpose    = "bsr"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey4"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

Refer to the list below for explanations of the parameters used in the example above:

  • disable mlock (bool: false) - Disables the server from executing the mlock 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 support mlock() 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.

boundary database init -config /etc/boundary.d/controller.hcl

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:

boundary database init \
   -skip-auth-method-creation \
   -skip-host-resources-creation \
   -skip-scopes-creation \
   -skip-target-creation \
   -config /etc/boundary.d/controller.hcl

Use the following command to view the help for additional options:

boundary database init -h

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:

  1. sudo systemctl enable boundary
  2. sudo systemctl start boundary

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.

HashiCorp recommends 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.

After configuring the controller, you should:

Edit this page on GitHub