hashicorp/boundary-enterprise repository overview

⁠Boundary Enterprise

⁠Disclaimer

This HashiCorp enterprise software is for use only by customers who have a valid and active license agreement with HashiCorp or an authorized HashiCorp reseller. If you do not have a valid license to use this software, you may not download or otherwise use it. All use of this software is subject to the terms and conditions of your license agreement, and all other rights are expressly reserved.

⁠Agreement

The following shall apply unless your organization has a separately signed agreement governing your use of the software made available here:

The software is subject to the license terms or community license (i.e. Mozilla Public License 2.0 or Business Source License), as applicable, located in the download package for the software, the IBM International Program License Agreement, the IBM International License Agreement for Evaluation of Programs (for evaluation uses), or the IBM International License Agreement for Early Release of Programs (alpha and beta releases), and the applicable License Information, copies of which are also available at https://www.ibm.com/terms⁠. In the event of a conflict between the license file in the download package and the noted IBM licenses above, the relevant IBM terms will apply. Please refer to the license terms prior to using the software. Your installation and use of the software constitute your acceptance of those terms. If you do not accept the terms, do not use the software.

⁠Usage

⁠Dev Mode

Due to the limitations of boundary dev running and maintaining a postgres docker container, it's not recommended to run dev mode inside docker. To do so will require knowledge of running docker-in-docker⁠, and the caveats associated with it.

⁠Default Configuration

The default behavior of the Boundary docker image is to run boundary server -config /boundary/config.hcl. The included config.hcl file is meant to serve as an example, and is not suitable for actual deployment. Please see the comments within the file for more information; full configuration details can be found on Boundary's documentation site.

⁠Postgres

The usage instructions in this README assume you have an external postgres database (version 12 or greater) to run boundary server with. If you want to get started quickly, you can start a local postgres in docker:

docker run -it -p 5432:5432 -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres postgres

The postgres URL setting is defined with env://BOUNDARY_POSTGRES_URL so it can be easily set with -e during docker run:

docker run \
    --network host \
    -e 'BOUNDARY_POSTGRES_URL=postgresql://postgres:[email protected]:5432/postgres?sslmode=disable' \
    -e 'BOUNDARY_LICENSE=<license>' \
    boundary-enterprise

⁠Controller

If using the image for a boundary controller, or controller and worker combination, a valid license must be supplied. The license can be provided as an environment variable:

docker run \
  --network host \
  -e 'BOUNDARY_POSTGRES_URL=postgresql://postgres:[email protected]:5432/postgres?sslmode=disable' \
  -e 'BOUNDARY_LICENSE=<license>' \
  boundary-enterprise

Or it can be specified in a custom config.hcl (assuming config.hcl is located at $(pwd)/config.hcl):

config.hcl:

controller {
  // other fields ommited
  // Also supports file:// and env:// to include the license in a separate file
  // or other environment variable.
  license = "<license>"
}

// other configuration omitted

docker run \
  --network host \
  -e 'BOUNDARY_POSTGRES_URL=postgresql://postgres:[email protected]:5432/postgres?sslmode=disable' \
  -v "$(pwd)":/boundary/ \
  boundary-enterprise

⁠Database Init

If you're starting with a new, unused postgres instance, initialize the database using the default config.hcl:

docker run \
  --network host \
  -e 'BOUNDARY_POSTGRES_URL=postgresql://postgres:[email protected]:5432/postgres?sslmode=disable' \
  -e 'BOUNDARY_LICENSE=<license>' \
  boundary-enterprise database init -config /boundary/config.hcl

If you want to run this with your own config.hcl (assuming config.hcl is located at $(pwd)/config.hcl):

docker run \
  --network host \
  -e 'BOUNDARY_POSTGRES_URL=postgresql://postgres:[email protected]:5432/postgres?sslmode=disable' \
  -v "$(pwd)":/boundary/ \
  boundary-enterprise database init -config /boundary/config.hcl

⁠Database Migration

If you are updating to a newer version of boundary with a database instance that was initialized with an older version, you will need to apply the database migrations:

docker run \
  --network host \
  -e 'BOUNDARY_POSTGRES_URL=postgresql://postgres:[email protected]:5432/postgres?sslmode=disable' \
  -e 'BOUNDARY_LICENSE=<license>' \
  boundary-enterprise database migrate -config /boundary/config.hcl

If you want to run this with your own config.hcl (assuming config.hcl is located at $(pwd)/config.hcl):

docker run \
  --network host \
  -e 'BOUNDARY_POSTGRES_URL=postgresql://postgres:[email protected]:5432/postgres?sslmode=disable' \
  -v "$(pwd)":/boundary/ \
  boundary-enterprise database migrate -config /boundary/config.hcl

⁠Server

Start a Boundary server using the default config.hcl:

docker run \
  --network host \
  -p 9200:9200 \
  -p 9201:9201 \
  -p 9202:9202 \
  -e 'BOUNDARY_POSTGRES_URL=postgresql://postgres:[email protected]:5432/postgres?sslmode=disable' \
  -e 'BOUNDARY_LICENSE=<license>' \
  boundary-enterprise

Start a Boundary server using your own config.hcl, assuming it's located at $(pwd)/config.hcl:

docker run \
  --network host \
  -p 9200:9200 \
  -p 9201:9201 \
  -p 9202:9202 \
  -v "$(pwd)":/boundary/ \
  -e 'BOUNDARY_POSTGRES_URL=postgresql://postgres:[email protected]:5432/postgres?sslmode=disable' \
  boundary-enterprise

⁠Worker

If using this image as a worker, either a worker that will connect to a boundary-enterprise controller, or as a Self-Managed Worker with HCP Boundary⁠, It is not necessary to provide the license via an environment variable or config, however the worker must connect with a licensed controller.

Assuming a config.hcl located at $(pwd)/config.hcl:

config.hcl:

// If using HCP Boundary
hcp_boundary_cluster_id = "https://<uuid>.boundary.hashicorp.cloud"

worker {
    // If using self managed controllers
    initial_upstreams = ["<controller address/dns>:9201"]

    // other configuration omitted
}
// other configuration omitted

docker run \
  --network host \
  -p 9202:9202 \
  -v "$(pwd)":/boundary/ \
  boundary-enterprise