Deployment

This section covers deploying Boundary Enterprise. Choose the deployment method that matches your environment:

• Deploy with Terraform — the recommended, automated path using the official HVD Terraform modules for AWS, Azure, or GCP.
• Deploy manually — a step-by-step manual installation of controllers and workers, suitable for private datacenters.

Deploy with Terraform

HashiCorp provides a set of official HVD modules to make it easier to deploy a Boundary Enterprise environment that adheres to the requirements and standards laid out in this HashiCorp Validated Design.

Platform-specific guidance

Deployment using Terraform modules

Select your cloud provider for the official HVD module links and platform-specific prerequisites.

Use these modules with Terraform to deploy a complete, end-to-end Boundary Enterprise deployment inside of your own cloud account.

While we have made efforts throughout this document to provide prescriptive best practices, we recognize that each organization has their own unique requirements and constraints when it comes to deploying infrastructure. Where feasible, we have included considerations needed when deploying Boundary in your cloud environment within the context of this Terraform module. The module contains additional capabilities that you may wish to review if the variables from this module do not suit your specific needs.

Deployment sequence overview

1. Deploy the prerequisite resources.
2. Obtain the license file.
3. Download the Boundary command-line tool (or the Boundary desktop client).
4. Download the Terraform command-line tool.
5. Obtain the HashiCorp Validated Design Terraform module for deploying Boundary Enterprise controllers and workers using the links for your CSP above.
6. Configure your cloud credentials.
7. Initialize your Terraform workspace.
8. Input your variables, including the values from your prerequisite deployment, in the module for deployment.
9. Create a Terraform plan for the controller.
10. Apply the plan.
11. Bootstrap the Boundary controller.
12. Create a Terraform plan for the worker(s).
13. Apply the plan.
14. Begin creating targets and using Boundary Enterprise.

Preparation

Create the certificate files

Create a standard X.509 certificate that to install on the Boundary servers. Refer to your organization's process on creating a new certificate that matches the DNS record you intend to direct users to when accessing Boundary.

Ensure the following files are available.

• The TLS certificate (tls-cert-secret.pub).
• The TLS private key (tls-cert-private.key).
• The CA bundle file from the certificate authority used to vend the certificate (tls-ca-bundle.pub).

Keep these files to hand, as they you need them later in the installation process.

Obtain the Boundary Enterprise license file

Obtain the Boundary Enterprise license file from your HashiCorp account team. This file contains a license key unique to your environment. Name the file something like boundary.hclic.

Keep this file to hand also, as you need it later in the installation process.

Download and install the Boundary command-line tool

• Download the appropriate package for your operating system from the HashiCorp Releases site.
• Unzip the package.
• Move the boundary binary (boundary.exe for Windows) to a directory in your system's PATH.
• Optional: Install Boundary Desktop client

Download and install the Terraform command-line tool

• Download the appropriate package for your operating system from the HashiCorp Releases site.
• Unzip the package.
• Move the Terraform binary (terraform.exe for Windows) to a directory in your system's PATH.

Download the Terraform module(s)

For the purpose of an automated deployment, Use these Terraform modules for your deployment, customizing where necessary. Once you have downloaded the module, navigate to the examples/default/ directory. Use this as the base working directory during the installation process.

Configure cloud credentials

Select your cloud provider below for cloud credentials configuration guidance.

Ensure the credentials have sufficient permissions to perform the necessary Terraform actions.

Installation

Initialize Terraform

Run terraform init to initialize your Terraform workspace and ensure there are no outstanding errors before continuing.

Configure variables for deployment

Review the terraform.tfvars.example file HashiCorp maintains in the examples/default/ directory for explanations of each relevant variable. There is a terraform.tfvars.example file in the respective module for each public cloud provider. Copy this file to a file called terraform.tfvars, and then fill in the values for each declared variable with the applicable values for your environment.

Create and apply Terraform plan

From the examples/default/ directory, generate a Terraform plan with the following command:

terraform plan -out=tfplan

Review the plan output, then apply the changes with this command:

terraform apply tfplan

Confirm the changes by typing yes when prompted.

Validate installation

After your terraform apply finishes, you can monitor the installation progress by connecting to your Boundary controller VM instance shell using SSH, AWS SSM, or Google IAP and observing the cloud-init (user_data) logs using the commands below in separate terminal windows.

tail -f /var/log/boundary-cloud-init.log
journalctl -xu cloud-final -f

The log files display the following message after the cloud-init (user_data) script finishes.

[INFO] boundary_custom_data script finished successfully!

Once the cloud-init script finishes, while still connected to the VM using SSH or equivalent, you can check the status of the Boundary service has the line below.

[INFO] boundary_custom_data script finished successfully!

From the terminal where you performed the terraform apply run the following command.

terraform output

Using the Terraform output command that references the load balancer name or IP address, create a new DNS entry that matches your TLS certificate and points to the load balancer for the Vault cluster. Set the following environment variable.

export BOUNDARY_ADDR="https://boundary.example.com"

Bootstrapping Boundary Enterprise

After deploying a Boundary Enterprise controller the system is in a partially initialized state. To complete initialization and configuration for initial authentication utilize the bootstrapping module.

Repeat the steps starting from the preceding Initialize Terraform section.

After bootstrapping is complete you can authenticate to the Boundary cluster using command-line tool or administrator UI.

Install Boundary workers

Utilize the Boundary Enterprise worker HVD module for AWS, Azure, or GCP and repeat the steps starting from Initialize Terraform for this new module.

After your terraform apply finishes, monitor the installation progress by connecting to your Boundary worker VM instance shell using SSH, AWS SSM, or Google IAP and observing the cloud-init (user_data) logs using the commands below in different terminal windows.

tail -f /var/log/boundary-cloud-init.log
journalctl -xu cloud-final -f

The log files display the following message after the cloud-init (user_data) script finishes.

[INFO] boundary_custom_data script finished successfully!

Once the cloud-init script finishes, while still connected to the VM using SSH you can check the status of the boundary service using the command below.

sudo systemctl status boundary

After the Boundary worker has deployed, it is visible in the Boundary clusters' workers list.

Deploy manually

Overview

This section details the steps to create a Boundary Enterprise cluster manually in a private datacenter. This guide assumes that you have already read the Recommended Deployment Architecture and Detailed Design section of this guide and have a basic understanding of the Boundary Enterprise architecture and the steps required to deploy it in a private datacenter.

This guide uses the following names and IP addresses for the Boundary Enterprise controllers and workers.

Prepare

License

Obtain your active Boundary Enterprise license file. If you do not have this file, contact your HashiCorp account team.

Servers

1. Refer to the Detailed Design section of the guide for more information on what to consider the sizing based on your environment.
2. Identify the availability zones within your datacenter where you plan to host your Boundary controllers and ingress/egress. For the rest of this document, we refer to these as zone1, zone2, zone3, and so on.
3. Build the servers. Ensure there is 1 Boundary Enterprise controller, ingress/egress worker per each of the 3 availability zones, for a total of 3 servers. For the rest of this document, we refer to these servers as controller1, controller2, controller3, ingressworker1, ingressworker2, ingressworker3, egressworker1, egressworker2, egressworker2, and so on.
4. Ensure you can log in to each server as a user with sudo or root privileges using SSH or equivalent.

Load balancer

1. A layer 4 load balancer exposes controller API and administrator UI using HTTPS (port 443) to Boundary Enterprise clients. The load balancer distributes Boundary Enterprise client requests to the controller's API port (default TCP 9200).
2. Another layer 4 load balancer exposes the controller's cluster port (default TCP 9201) for workers session authorization, credentials, and so on.
3. Refer to the Detailed Design section of the guide for more information on how to configure the load balancer.

PostgreSQL

Controllers are stateless and manage all configurations through an external PostgreSQL database. We recommend configuring the PostgreSQL database for high availability. Please refer to PostgreSQL High Availability, Load Balancing, and Replication. If you use a managed service, refer to your provider's PostgreSQL high availability documentation.

Storage for session recording

We recommend using S3-compliant Object Storage for audit logging and session recording. Refer to the Detailed Design section of the guide for more information on how to configure storage for session recording.

Boundary Enterprise controller configuration

TLS

Create an X.509 certificate. Install this onto each of the Boundary Enterprise controllers. Refer to your organization's process on creating a new certificate that matches the DNS record you intend to direct users to when accessing Boundary Enterprise. In this case, the DNS record pointing at the load balancer: boundary.domain. Please replace boundary.domain with your actual domain name.

You need these files:

1. The certificate (cert.pem).
2. The certificate's private key (key.pem).
3. The certificate authority bundle from a trusted certificate authority (bundle.pem).

You may have to create a new directory to store the certificate material at /etc/boundary.d/tls.

ls -l /etc/boundary.d/tls
-rw-r----- 1 boundary boundary 1801 Oct 17 03:47 bundle.pem
-rw-r----- 1 boundary boundary 1842 Oct 17 03:47 cert.pem
-rw-r----- 1 boundary boundary 1679 Oct 17 03:47 key.pem

Specify the following configuration in the /etc/boundary.d/controller.hcl file to contain the TLS certificates configuration.

# API listener configuration block
listener "tcp" {
  address              = "0.0.0.0:9200"
  purpose              = "api"
  tls_disable          = false
  tls_cert_file        = "/etc/boundary.d/tls/cert.pem"
  tls_key_file         = "/etc/boundary.d/tls/key.pem"
  tls_client_ca_file   = "/etc/boundary.d/tls/bundle.pem"
  cors_enabled         = true
  cors_allowed_origins = ["*"]
}

# Ops listener for operations like health checks for load balancers
listener "tcp" {
  address            = "0.0.0.0:9203"
  purpose            = "ops"
  tls_disable        = false
  tls_cert_file      = "/etc/boundary.d/tls/cert.pem"
  tls_key_file       = "/etc/boundary.d/tls/key.pem"
  tls_client_ca_file = "/etc/boundary.d/tls/bundle.pem"
}

KMS for controllers

You need four KMS keys:

1. root
   • The root key is the primary encryption key used by Boundary Enterprise.
2. worker-auth
   • The controller and worker share this to authenticate a worker to the controller.
3. recovery
   • Use this key for rescue/recovery operations in case of system issues or when normal authentication methods are unavailable.
4. bsr
   • Use this key for session recording capabilities. Recording of session data uses this key and ensures the integrity of those recordings.

Specify the following configuration in the /etc/boundary.d/controller.hcl file to contain the KMS keys configuration.

# Root KMS Key (managed by AWS KMS in this example)
kms "awskms" {
  purpose    = "root"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey1"
}

# Recovery KMS Key (managed by AWS KMS in this example)
kms "awskms" {
  purpose    = "recovery"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey2"
}

# Worker-Auth KMS Key (managed by AWS KMS in this example)
kms "awskms" {
  purpose    = "worker-auth"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey3"
}

# BSR KMS Key (managed by AWS KMS in this example)
kms "awskms" {
  purpose    = "bsr"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey4"
}

Refer to the Vault Transit page to configure Boundary Enterprise to use Vault's Transit secret engine for key management. If you use a managed service, refer to our KMS documentation for guidance.

Prepare controller configuration to initialize a PostgreSQL database

Use the following in the /etc/boundary.d/controller.hcl file to configure the database URL.

# Controller configuration block
controller {
  name        = "<controller1>"           # update here for other controllers
  description = "<Boundary Controller 1>" # update here for other controllers
  database {
    url = "postgresql://POSTGRESQL_CONNECTION_STRING"
  }

  license = "file:////opt/boundary/license/license.hclic"
}

Prepare Boundary Enterprise controller configuration

Populate the /etc/boundary.d/controller.hcl file with the configuration information below.

Use the following controller configuration on each controller node, replacing the name, description, database URL, license path, listener IP address and KMS configuration in each case.

# disable memory from being swapped to disk
disable_mlock = true
telemetry {
  prometheus_retention_time = "24h"
  disable_hostname          = true
}

# Controller configuration block
controller {
  name        = "<controller1>"                      # update here for other controllers
  description = "<Boundary Enterprise Controller 1>" # update here for other controllers
  database {
    url = "postgresql://POSTGRESQL_CONNECTION_STRING"
  }

  license = "file:////opt/boundary/license/license.hclic"
}

# API listener configuration block
listener "tcp" {
  address              = "0.0.0.0:9200"
  purpose              = "api"
  tls_disable          = false
  tls_cert_file        = "/etc/boundary.d/tls/cert.pem"
  tls_key_file         = "/etc/boundary.d/tls/key.pem"
  tls_client_ca_file   = "/etc/boundary.d/tls/bundle.pem"
  cors_enabled         = true
  cors_allowed_origins = ["*"]
}

# Data-plane listener configuration block (used for worker coordination)
listener "tcp" {
  address = "<10.0.253.11>:9201" # update here for other controllers IP address
  purpose = "cluster"
}

# Ops listener for operations like health checks for load balancers
listener "tcp" {
  address            = "0.0.0.0:9203"
  purpose            = "ops"
  tls_disable        = false
  tls_cert_file      = "/etc/boundary.d/tls/cert.pem"
  tls_key_file       = "/etc/boundary.d/tls/key.pem"
  tls_client_ca_file = "/etc/boundary.d/tls/bundle.pem"
}

# Events (logging) configuration. This configured 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)
kms "awskms" {
  purpose    = "root"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey1"
}

# Recovery KMS Key
kms "awskms" {
  purpose    = "recovery"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey2"
}

# Worker-Auth KMS Key (in this example uses KMS authenticated workers)
kms "awskms" {
  purpose    = "worker-auth"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey3"
}

# BSR KMS Key (in this example uses KMS for the session recording feature)
kms "awskms" {
  purpose    = "bsr"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey4"
}

Initialize a PostgreSQL database

Before you can start Boundary Enterprise, you must initialize the database from one controller.

The following command initializes a Boundary Enterprise's database with the configuration specified in the /etc/boundary.d/controller.hcl file:

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

Starting Boundary Enterprise controller service

When the configuration files are in place on each Boundary Enterprise controller, you can proceed to enable and start the binary using systemd on each of the Boundary Enterprise controller nodes.

Perform these steps on all Boundary Enterprise controllers:

1. Create a boundary user, and create directories for Boundary Enterprise configuration owned by this user.

   adduser --system --group boundary || true
   mkdir -p /etc/boundary.d /etc/boundary.d/tls /opt/boundary/license /var/log/boundary
   chown -R boundary:boundary /etc/boundary.d /var/log/boundary
   

2. Download the Boundary Enterprise package from HashiCorp. Unzip the package and move the boundary binary to a shared PATH location such as /usr/local/bin, owned by the boundary user.

   curl -O https://releases.hashicorp.com/boundary/0.17.1+ent/boundary_0.17.1+ent_linux_amd64.zip
   unzip boundary_0.17.1+ent_linux_amd64.zip
   mv boundary /usr/local/bin/
   chown boundary:boundary /usr/local/bin/boundary
   

3. Add the license file, certificate files, and relevant configuration file to /etc/boundary.d. In the end, the directory looks like the below.

   $ chown boundary:boundary /etc/boundary.d/*
   $ chmod 640 /etc/boundary.d/*
   $ ls -l /etc/boundary.d/
   -rw-r-----  1 boundary boundary 1652 Oct 17 03:47 controller.hcl
   drwxr-x---  2 boundary boundary 4096 Oct 17 03:47 tls
   
   $ ls -l /etc/boundary.d/tls
   -rw-r----- 1 boundary boundary 1801 Oct 17 03:47 bundle.pem
   -rw-r----- 1 boundary boundary 1842 Oct 17 03:47 cert.pem
   -rw-r----- 1 boundary boundary 1679 Oct 17 03:47 key.pem
   
   $ ls -l /opt/boundary/license
   -rw-rw-r-- 1 root     root     3514 Aug 15 18:21 EULA.txt
   -rw-rw-r-- 1 root     root     4922 Aug 15 18:21 LICENSE.txt
   -rw-rw-r-- 1 root     root     9518 Aug 15 18:21 TermsOfEvaluation.txt
   -rw-r--r-- 1 root     root     1163 Oct 17 03:47 license.hclic
   
   $ ls -la /var/log/boundary
   total 8
   drwxr-x---  2 boundary boundary 4096 Oct 17 06:23 .
   drwxrwxr-x 11 root     syslog   4096 Oct 17 06:23 ..
   

4. Create a systemd unit file for the Boundary Enterprise service, then load it into systemd. Note that the ExecStart line runs the boundary binary pointing to your controller.hcl file.

   $ cat << EOF >> /etc/systemd/system/boundary.service
   [Unit]
   Description="HashiCorp Boundary Enterprise"
   Documentation=https://developer.hashicorp.com/boundary/docs
   Requires=network-online.target
   After=network-online.target
   ConditionFileNotEmpty=/etc/boundary.d/controller.hcl
   StartLimitIntervalSec=60
   StartLimitBurst=3
   
   [Service]
   User=boundary
   Group=boundary
   ProtectSystem=full
   ProtectHome=read-only
   PrivateTmp=yes
   PrivateDevices=yes
   SecureBits=keep-caps
   AmbientCapabilities=CAP_IPC_LOCK
   CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
   NoNewPrivileges=yes
   ExecStart=/usr/bin/boundary server -config=/etc/boundary.d/controller.hcl
   ExecReload=/bin/kill --signal HUP $MAINPID
   KillMode=process
   KillSignal=SIGINT
   Restart=on-failure
   RestartSec=5
   TimeoutStopSec=30
   LimitNOFILE=65536
   LimitMEMLOCK=infinity
   
   [Install]
   WantedBy=multi-user.target
   EOF
   

   systemctl daemon-reload
   systemctl enable boundary
   

5. Start the Boundary Enterprise controller service.

   systemctl start boundary
   

Boundary Enterprise ingress workers configuration

KMS for ingress workers

Get the worker-auth KMS key from the KMS for controllers section. This key enables secure communication between workers and controllers, ensuring that only authorized workers can connect to each other.

Specify the following configuration in the /etc/boundary.d/worker.hcl file to contain the KMS keys configuration.

# Worker-auth KMS key (managed by AWS KMS in this example)
kms "awskms" {
  purpose    = "worker-auth"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey3"
}

Prepare ingress workers configuration

Populate the /etc/boundary.d/worker.hcl file with the configuration information below replacing content prompted in angled brackets with the correct characters for your deployment.

All three ingress workers' configurations are the same except the worker configuration stanza.

# disable memory from being swapped to disk
disable_mlock = true
telemetry {
  prometheus_retention_time = "24h"
  disable_hostname          = true
}

# worker block for configuring the specifics of the worker service
worker {
  public_addr = "<10.0.253.101>"      # update here for other ingress workers ip address
  name = "<ingressworker1>"           # update here for other ingress workers name
  initial_upstreams = ["<controller_cluster_lb_address>:9201"]
  recording_storage_path="/opt/boundary/bsr"
  recording_storage_minimum_available_capacity="500MB"
  tags {"app"="worker","env"="uat","bsr"="enabled","worker-type"="ingress"}
}

# listener denoting this is a worker proxy
listener "tcp" {
  address            = "0.0.0.0:9202"
  purpose            = "proxy"
}

# Ops listener for operations like health checks for ingress workers
listener "tcp" {
  address     = "0.0.0.0:9203"
  purpose     = "ops"
  tls_disable = true
}

# Events (logging) configuration. This
# configured logging for ALL events to both
# stderr and a file at /var/log/boundary/ingress-worker.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 = "ingress-worker.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# kms block for encrypting the authentication PKI material
# Worker-Auth KMS Key (managed by AWS KMS in this example)
kms "awskms" {
  purpose    = "worker-auth"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey3"
}

Starting Boundary Enterprise ingress worker service

When the configuration files are in place on each Boundary Enterprise ingress worker, you can proceed to enable and start the binary using systemd on each of the Boundary Enterprise ingress worker nodes.

Perform these steps on all Boundary Enterprise ingress workers:

1. Create a boundary user, and create directories for Boundary Enterprise configuration owned by this user.

   adduser --system --group boundary || true
   mkdir -p /etc/boundary.d /opt/boundary/bsr /var/log/boundary
   chown -R boundary:boundary /etc/boundary.d /opt/boundary/bsr /var/log/boundary
   

2. Use the official well-architected method to download the Boundary Enterprise binary and signature files from HashiCorp and confirm the integrity using the gpg binary. Unzip the package and move the boundary binary to a shared PATH location such as /usr/local/bin, owned by the boundary user as per the below.

   unzip boundary_0.17.1+ent_linux_amd64.zip
   mv boundary /usr/local/bin/
   chown boundary:boundary /usr/local/bin/boundary
   

3. Add relevant configuration file to /etc/boundary.d. In the end, the directory looks like this:

   $ chown boundary:boundary /etc/boundary.d/*
   $ chmod 640 /etc/boundary.d/*
   $ ls -l /etc/boundary.d/
   -rw-r-----  1 boundary boundary  704 Oct 17 06:23 worker.hcl
   
   $ ls -l /opt/boundary/
   drwxr-x--- 3 boundary boundary 4096 Oct 17 06:23 bsr
   drwxr-x--- 2 boundary boundary 4096 Oct 17 06:23 data
   
   $ ls -la /var/log/boundary
   total 8
   drwxr-x---  2 boundary boundary 4096 Oct 17 06:23 .
   drwxrwxr-x 11 root     syslog   4096 Oct 17 06:23 ..
   

4. Create a systemd unit file for the Boundary Enterprise service, then load it into systemd. Note that the ExecStart line runs the boundary binary pointing to your worker.hcl file:

   $ cat << EOF >> /etc/systemd/system/boundary.service
   [Unit]
   Description="HashiCorp Boundary Enterprise"
   Documentation=https://www.boundaryproject.io/docs/
   Requires=network-online.target
   After=network-online.target
   ConditionFileNotEmpty=/etc/boundary.d/worker.hcl
   StartLimitIntervalSec=60
   StartLimitBurst=3
   
   [Service]
   User=boundary
   Group=boundary
   ProtectSystem=full
   ProtectHome=read-only
   PrivateTmp=yes
   PrivateDevices=yes
   SecureBits=keep-caps
   AmbientCapabilities=CAP_IPC_LOCK
   CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
   NoNewPrivileges=yes
   ExecStart=/usr/bin/boundary server -config=/etc/boundary.d/worker.hcl
   ExecReload=/bin/kill --signal HUP $MAINPID
   KillMode=process
   KillSignal=SIGINT
   Restart=on-failure
   RestartSec=5
   TimeoutStopSec=30
   LimitNOFILE=65536
   LimitMEMLOCK=infinity
   
   [Install]
   WantedBy=multi-user.target
   EOF
   

   systemctl daemon-reload
   systemctl enable boundary
   

5. Start the Boundary Enterprise ingress worker service.

   systemctl start boundary
   

Boundary Enterprise egress workers configuration

KMS for egress workers

Get the worker-auth KMS key from the KMS for controllers section. This key enables secure communication between workers and controllers, ensuring that only authorized workers can connect to each other.

Use the following KMS configuration block in the /etc/boundary.d/worker.hcl file.

# Worker-Auth KMS Key (managed by AWS KMS in this example)
kms "awskms" {
  purpose    = "worker-auth"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey3"
}

Prepare egress workers configuration

Populate the /etc/boundary.d/worker.hcl file with the configuration information below.

The configuration of all three egress workers must be identical except the worker and kms blocks. Amend these as necessary.

# disable memory from being swapped to disk
disable_mlock = true
telemetry {
  prometheus_retention_time = "24h"
  disable_hostname          = true
}

# worker block for configuring the specifics of the worker service
worker {
  public_addr = "<10.0.253.201>" # update here for other egress workers IP address
  name = "<egressworker1>"       # update here for other egress workers name
  initial_upstreams = ["<ingress_lb_address>:9202"]
  recording_storage_path="/opt/boundary/bsr"
  recording_storage_minimum_available_capacity="500MB"
  tags {"app"="worker","env"="uat","bsr"="enabled","worker-type"="egress"}
}

# listener denoting this is a worker proxy
listener "tcp" {
  address            = "0.0.0.0:9202"
  purpose            = "proxy"
}

# Ops listener for operations like health checks for ingress workers
listener "tcp" {
  address     = "0.0.0.0:9203"
  purpose     = "ops"
  tls_disable = true
}

# Events (logging) configuration. This
# configured logging for ALL events to both
# stderr and a file at /var/log/boundary/egress-worker.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 = "egress-worker.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# kms block for encrypting the authentication PKI material
# Worker-Auth KMS Key (managed by AWS KMS in this example)
kms "awskms" {
  purpose    = "worker-auth"
  region     = "ap-southeast-1"
  kms_key_id = "abcd1234-a123-456a-a12b-aexamplekey3"
}

Starting Boundary Enterprise egress worker service

When the configuration files are in place on each Boundary Enterprise egress worker, enable the binary using systemd on each of the Boundary Enterprise egress worker nodes.

Perform these steps on all Boundary Enterprise egress workers:

1. Create a boundary user, and create directories for Boundary Enterprise configuration owned by this user.

   adduser --system --group boundary || true
   mkdir -p /etc/boundary.d /opt/boundary/bsr /var/log/boundary
   chown -R boundary:boundary /etc/boundary.d /opt/boundary/bsr /var/log/boundary
   

2. Use the official well-architected method to download the Boundary Enterprise binary and signature files from HashiCorp and confirm the integrity using the gpg binary. Unzip the package and move the boundary binary to a shared PATH location such as /usr/local/bin, owned by the boundary user as per the below.

   unzip boundary_0.17.1+ent_linux_amd64.zip
   mv boundary /usr/local/bin/
   chown boundary:boundary /usr/local/bin/boundary
   

3. Add relevant configuration file to /etc/boundary.d. In the end, the directory looks like this:

   $ chown boundary:boundary /etc/boundary.d/*
   $ chmod 640 /etc/boundary.d/*
   $ ls -l /etc/boundary.d/
   -rw-r-----  1 boundary boundary  704 Oct 17 06:23 worker.hcl
   
   $ ls -l /opt/boundary/
   drwxr-x--- 3 boundary boundary 4096 Oct 17 06:23 bsr
   drwxr-x--- 2 boundary boundary 4096 Oct 17 06:23 data
   
   $ ls -la /var/log/boundary
   total 8
   drwxr-x---  2 boundary boundary 4096 Oct 17 06:23 .
   drwxrwxr-x 11 root     syslog   4096 Oct 17 06:23 ..
   

4. Create a systemd unit file for the Boundary Enterprise service, then load it into systemd. Note that the ExecStart line runs the boundary binary pointing to your worker.hcl file:

   $ cat << EOF >> /etc/systemd/system/boundary.service
   [Unit]
   Description="HashiCorp Boundary Enterprise"
   Documentation=https://www.boundaryproject.io/docs/
   Requires=network-online.target
   After=network-online.target
   ConditionFileNotEmpty=/etc/boundary.d/worker.hcl
   StartLimitIntervalSec=60
   StartLimitBurst=3
   
   [Service]
   User=boundary
   Group=boundary
   ProtectSystem=full
   ProtectHome=read-only
   PrivateTmp=yes
   PrivateDevices=yes
   SecureBits=keep-caps
   AmbientCapabilities=CAP_IPC_LOCK
   CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
   NoNewPrivileges=yes
   ExecStart=/usr/bin/boundary server -config=/etc/boundary.d/worker.hcl
   ExecReload=/bin/kill --signal HUP $MAINPID
   KillMode=process
   KillSignal=SIGINT
   Restart=on-failure
   RestartSec=5
   TimeoutStopSec=30
   LimitNOFILE=65536
   LimitMEMLOCK=infinity
   
   [Install]
   WantedBy=multi-user.target
   EOF
   

   systemctl daemon-reload
   systemctl enable boundary
   

5. Start the Boundary Enterprise egress worker service.

   systemctl start boundary
   

Next steps

After setting up a Boundary Enterprise cluster, it is essential to perform initial configuration steps to ensure the environment is secure, functional, and ready for use. Refer to Post-installation configuration in this guide.