Production Installation

Installing Boundary in a production setting requires prerequisits for infrastructure. At the most basic level, Boundary operators should run a minimum of 3 controllers and 3 workers. Running 3 of each server type gives a fundamental level of high availability for the control plane (controller), as well as bandwidth for number of sessions on the data plane (worker). Both server type should be ran in a fault tolerant setting, that is, in a self-healing environment such as an auto-scaling group. The documentation here does not cover self-healing infrastructure and assumes the operator has their preferred scheduling methods for these environments.

Network Requirements

  • Client -> Controller port is :9200
  • Controller -> Worker port is :9201
  • Client must have access to Controller on :9200
  • :9201 must be open between Worker and Controller
  • Workers must have a route and port access to the targets which they service

Architecture

The general architecture for the server infrastructure requires 3 controllers and 3 workers. The documentation here uses virtual machines running on Amazon EC2 as the example environment, but this use case can be extrapolated to almost any cloud platform to suit operator needs:

Production - 图1

As shown above, Boundary is broken up into its controller and worker server components across 3 EC2 instances, in 3 separate subnets, in three separate availability zones, with the controller API and UI being publically exposed by an application load balancer (ALB). The worker and controller VM’s are in independent auto-scaling groups, allowing them to maintain their exact capacity.

Boundary requires an external Postgres and KMS. In the example above, we’re using AWS managed services for these components. For Postgres, we’re using RDS and for KMS we’re using Amazon’s Key Management Service.

Architecture Breakdown

API and Console Load Balancer

Load balancing the controller allows operators to secure the ingress to the Boundary system. We recommend placing all Boundary server’s in private networks and using load balancing tecniques to expose services such as the API and administrative console to public networks. In the production architecture, we recommend load balancing using a layer 7 load balancer and further constraining ingress to that load balancer with layer 4 constraints such as security groups or IP tables.

For general configuration, we recommend the following:

  • HTTPS listener with valid TLS certificate for the domain it’s serving or TLS passthrough
  • Health check port should use :9200 with TCP protocol

Controller Configuration

When running Boundary controller as a service we recommend storing the file at /etc/boundary-controller.hcl. A boundary user and group should exist to manage this configuration file and to further restrict who can read and modify it.

Example controller configuration:

  1. # Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.html
  2. disable_mlock = true
  4. telemetry {
  5.   # prometheus is not currently implemented
  6.   prometheus_retention_time = "24h"
  7.   disable_hostname = true
  8. }
  10. # Controller configuration block
  11. controller {
  12.   # This name attr must be unique!
  13.   name = "demo-controller-${count.index}"
  14.   # Description of this controller
  15.   description = "A controller for a demo!"
  16. }
  18. # API listener configuration block
  19. listener "tcp" {
  20.   # Should be the address of the NIC that the controller server will be reached on
  21.   address = "${self.private_ip}:9200"
  22.   # The purpose of this listener block
  23.     purpose = "api"
  24.   # Should be enabled for production installs
  25.     tls_disable = true
  26.   # Enable CORS for the Admin UI
  27.     cors_enabled = true
  28.     cors_allowed_origins = ["*"]
  29. }
  31. # Data-plane listener configuration block (used for worker coordination)
  32. listener "tcp" {
  33.   # Should be the IP of the NIC that the worker will connect on
  34.   address = "${self.private_ip}:9201"
  35.   # The purpose of this listener
  36.     purpose = "cluster"
  37.   # Should be enabled for production installs
  38.     tls_disable = true
  39. }
  41. # Root KMS configuration block: this is the root key for Boundary
  42. # Use a production KMS such as AWS KMS in production installs
  43. kms "aead" {
  44.     purpose = "root"
  45.     aead_type = "aes-gcm"
  46.     key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="
  47.     key_id = "global_root"
  48. }
  50. # Worker authorization KMS
  51. # Use a production KMS such as AWS KMS for production installs
  52. # This key is the same key used in the worker configuration
  53. kms "aead" {
  54.     purpose = "worker-auth"
  55.     aead_type = "aes-gcm"
  56.     key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  57.     key_id = "global_worker-auth"
  58. }
  60. # Recovery KMS block: configures the recovery key for Boundary
  61. # Use a production KMS such as AWS KMS for production installs
  62. kms "aead" {
  63.     purpose = "recovery"
  64.     aead_type = "aes-gcm"
  65.     key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  66.     key_id = "global_recovery"
  67. }
  69. # Database URL for postgres. This can be a direct "postgres://"
  70. # URL, or it can be "file://" to read the contents of a file to
  71. # supply the url, or "env://" to name an environment variable
  72. # that contains the URL.
  73. database {
  74.   url = "postgresql://boundary:boundarydemo@${aws_db_instance.boundary.endpoint}/boundary"
  75. }
  1. # Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.htmldisable_mlock = true
  2. telemetry {  # prometheus is not currently implemented  prometheus_retention_time = "24h"  disable_hostname = true}
  3. # Controller configuration blockcontroller {  # This name attr must be unique!  name = "demo-controller-${count.index}"  # Description of this controller  description = "A controller for a demo!"}
  4. # API listener configuration blocklistener "tcp" {  # Should be the address of the NIC that the controller server will be reached on  address = "${self.private_ip}:9200"  # The purpose of this listener block    purpose = "api"  # Should be enabled for production installs    tls_disable = true  # Enable CORS for the Admin UI    cors_enabled = true    cors_allowed_origins = ["*"]}
  5. # 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 = "${self.private_ip}:9201"  # The purpose of this listener    purpose = "cluster"  # Should be enabled for production installs    tls_disable = true}
  6. # Root KMS configuration block: this is the root key for Boundary# Use a production KMS such as AWS KMS in production installskms "aead" {    purpose = "root"    aead_type = "aes-gcm"    key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="    key_id = "global_root"}
  7. # Worker authorization KMS# Use a production KMS such as AWS KMS for production installs# This key is the same key used in the worker configurationkms "aead" {    purpose = "worker-auth"    aead_type = "aes-gcm"    key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="    key_id = "global_worker-auth"}
  8. # Recovery KMS block: configures the recovery key for Boundary# Use a production KMS such as AWS KMS for production installskms "aead" {    purpose = "recovery"    aead_type = "aes-gcm"    key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="    key_id = "global_recovery"}
  9. # Database URL for postgres. This can be a direct "postgres://"# URL, or it can be "file://" to read the contents of a file to# supply the url, or "env://" to name an environment variable# that contains the URL.database {  url = "postgresql://boundary:boundarydemo@${aws_db_instance.boundary.endpoint}/boundary"}

Worker Configuration

  1. listener "tcp" {
  2.     purpose = "proxy"
  3.     tls_disable = true
  4. }
  6. worker {
  7.   # Name attr must be unique
  8.     name = "demo-worker-${count.index}"
  9.     description = "A default worker created demonstration"
  10.     controllers = [
  11.     "${aws_instance.controller[0].private_ip}",
  12.     "${aws_instance.controller[1].private_ip}",
  13.     "${aws_instance.controller[2].private_ip}"
  14.   ]
  15. }
  17. # must be same key as used on controller config
  18. kms "aead" {
  19.     purpose = "worker-auth"
  20.     aead_type = "aes-gcm"
  21.     key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  22.     key_id = "global_worker-auth"
  23. }
  1. listener "tcp" {    purpose = "proxy"    tls_disable = true}
  2. worker {  # Name attr must be unique    name = "demo-worker-${count.index}"    description = "A default worker created demonstration"    controllers = [    "${aws_instance.controller[0].private_ip}",    "${aws_instance.controller[1].private_ip}",    "${aws_instance.controller[2].private_ip}"  ]}
  3. # must be same key as used on controller configkms "aead" {    purpose = "worker-auth"    aead_type = "aes-gcm"    key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="    key_id = "global_worker-auth"}

name must be unique!

Installation

TYPE below can be either worker or controller.

  1. /etc/boundary-${TYPE}.hcl: Configuration file for the boundary service See above example configurations.

  2. /usr/local/bin/boundary: The Boundary binary Can build from https://github.com/hashicorp/boundary or download binary from our release pages.

  3. /etc/systemd/system/boundary-${TYPE}.service: Systemd unit file for the Boundary service Example:

  1. [Unit]
  2. Description=${NAME} ${TYPE}
  4. [Service]
  5. ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl
  6. User=boundary
  7. Group=boundary
  8. LimitMEMLOCK=infinity
  9. Capabilities=CAP_IPC_LOCK+ep
  10. CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
  12. [Install]
  13. WantedBy=multi-user.target
  1. [Unit]Description=${NAME} ${TYPE}
  2. [Service]ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hclUser=boundaryGroup=boundaryLimitMEMLOCK=infinityCapabilities=CAP_IPC_LOCK+epCapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
  3. [Install]WantedBy=multi-user.target

Here’s a simple install script that creates the boundary group and user, installs the systemd unit file and enables it at startup:

  1. #!/bin/bash
  2. # Installs the boundary as a service for systemd on linux
  3. # Usage: ./install.sh <worker|controller>
  5. TYPE=$1
  6. NAME=boundary
  8. sudo cat << EOF > /etc/systemd/system/${NAME}-${TYPE}.service
  9. [Unit]
  10. Description=${NAME} ${TYPE}
  12. [Service]
  13. ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl
  14. User=boundary
  15. Group=boundary
  16. LimitMEMLOCK=infinity
  17. Capabilities=CAP_IPC_LOCK+ep
  18. CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
  20. [Install]
  21. WantedBy=multi-user.target
  22. EOF
  24. # Add the boundary system user and group to ensure we have a no-login
  25. # user capable of owning and running Boundary
  26. sudo adduser --system --group boundary || true
  27. sudo chown boundary:boundary /etc/${NAME}-${TYPE}.hcl
  28. sudo chown boundary:boundary /usr/local/bin/boundary
  30. # Make sure to initialize the DB before starting the service. This will result in
  31. # a database already initialized warning if another controller or worker has done this
  32. # already, making it a lazy, best effort initialization
  33. if [ "${TYPE}" = "controller" ]; then
  34.   sudo /usr/local/bin/boundary database init -config /etc/${NAME}-${TYPE}.hcl || true
  35. fi
  37. sudo chmod 664 /etc/systemd/system/${NAME}-${TYPE}.service
  38. sudo systemctl daemon-reload
  39. sudo systemctl enable ${NAME}-${TYPE}
  40. sudo systemctl start ${NAME}-${TYPE}
  1. #!/bin/bash# Installs the boundary as a service for systemd on linux# Usage: ./install.sh <worker|controller>
  2. TYPE=$1NAME=boundary
  3. sudo cat << EOF > /etc/systemd/system/${NAME}-${TYPE}.service[Unit]Description=${NAME} ${TYPE}
  4. [Service]ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hclUser=boundaryGroup=boundaryLimitMEMLOCK=infinityCapabilities=CAP_IPC_LOCK+epCapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
  5. [Install]WantedBy=multi-user.targetEOF
  6. # Add the boundary system user and group to ensure we have a no-login# user capable of owning and running Boundarysudo adduser --system --group boundary || truesudo chown boundary:boundary /etc/${NAME}-${TYPE}.hclsudo chown boundary:boundary /usr/local/bin/boundary
  7. # Make sure to initialize the DB before starting the service. This will result in# a database already initialized warning if another controller or worker has done this# already, making it a lazy, best effort initializationif [ "${TYPE}" = "controller" ]; then  sudo /usr/local/bin/boundary database init -config /etc/${NAME}-${TYPE}.hcl || truefi
  8. sudo chmod 664 /etc/systemd/system/${NAME}-${TYPE}.servicesudo systemctl daemon-reloadsudo systemctl enable ${NAME}-${TYPE}sudo systemctl start ${NAME}-${TYPE}

Postgres Configuration

TBD

KMS Configuration

TBD