Create & Configuring Hashicorp Boundary worker

I have installed hashicorp boundary controller in one VM and Boundary Desktop Client in another machine. my target resource is another VM. now where to create or install boundary worker and how to create, configure & register worker.
All these boundary components are hosted on separate VMs.
Please advise a simple way to configure boundary worker.

There are a couple of things you can do. The simplest is either to set up a new VM for the worker, or to modify the existing controller config to add a worker config as well. You could also install the worker on the target itself (in which case it’s a little bit like an on-host agent, which is useful in some scenarios to access some things normally restricted to localhost access) or on the client machine itself (which is fine for learning purposes, but not very useful in a real-world scenario).

1 Like

You can install a worker anywhere so long as it satisfies the following requirements:

  • You can reach the worker from the client
  • The worker can reach the target endpoint

If you are not on the Community edition, the first bullet point changes slightly – you can create a chain of workers, and you need to be able to reach an ingress worker from your client, and an egress worker has to be able to reach the target endpoint.

1 Like

@jeff & @omkensey
Thank you for replying, however, I am getting the below error while starting the PKI worker:

“error”, “data”: {“error running first status check post hook: worker.checkControllerConnection: error checking boundary controller connection: worker.checkHcpConnection: ipstream is not a licensed Boundary controller or worker\nworker.checkEntControllerConnection: error fields: {}, “id”: “e_6m7dhdhgD”, version”: “v0.1”, “op”: “worker.(worker).sendWorkerStatus”}

==>Boundary server self-terminating.

Is this mean it is not connecting to boundary controller. What causing this.

So basically, I have self-hosted worker and controller in my lab.


What version of the worker are you using? The version should be printed in the logs when the worker starts, or boundary version on the worker machine should tell you.

boundary-worker version is 0.12.3+hcp

Aha, that’s the issue. The boundary-worker release was just for HCP, since there was no standalone Boundary Enterprise yet at that point – so it checks for whether the control plane is HCP Boundary and if it’s not, it won’t run. If you’re running self-hosted community-edition Boundary, just use the same binary or container for the worker(s) that you’re using for the control plane.

I am using boundary version (0.13.0), it does not have “ent” in the version, how can I use the same binary for installing boundary worker. OR
as long as boundary is installed, I only need to create pki-worker-hcl file.

in my case, everything is self-hosted nothing in HCP or any other cloud.

I am getting confused with worker installation and its configuration.

also, which version I should use for both boundary controller and worker?

Please confirm

Since you’re running the community edition, just make sure you copy the same Boundary executable binary to both the worker and the controller systems (I’m assuming they’re separate VMs or whatever). You can run the same executable as either a worker or a controller depending on what config file you start it with.

If you’re using Debian, Ubuntu, Red Hat, CentOS, or some other APT or RPM-based distribution that the HashiCorp package repos support (there’s a list of supported distributions at that link), the easiest way to install it is probably to add the HashiCorp package repo for your distribution and install Boundary using that.

Once you have Boundary installed on your workers and controllers, to create a PKI worker you need to start the controllers first, then you can either use the worker-led or controller-led worker authorization flow to register a worker with the controllers.

So the basic order of operations is:

  1. Install Boundary on controllers and workers (same Boundary version on both types of systems)
  2. Create controller config files on the controllers and start Boundary with them.
  3. Register workers with the controllers – either:
    a. Create worker config files, start the workers with them, and then use worker-generated tokens to register the workers with the controllers
    b. Create the worker registration on the controllers, create worker config files with the controller-generated tokens in them, then start the workers with them

At that point you should be able to log into the Boundary admin GUI and see your registered workers there.

Thank for the steps mentioned however, I am not sure about controller config files on the controller.
I have updated /etc/boundary.d/controller.hcl file with below code but it is failing when trying to enable the service (systemctl status boundary
● boundary.service - “HashiCorp Boundary - Identity-based access management for dynamic infrastructure”
** Loaded: loaded (/usr/lib/systemd/system/boundary.service; enabled; vendor preset: disabled)**
** Active: failed (Result: exit-code) since Mon 2024-01-08 17:17:34 AEDT; 56s ago**
** Docs: Documentation | Boundary | HashiCorp Developer**
** Process: 1650 ExecStart=/usr/bin/boundary server -config=/etc/boundary.d/boundary.hcl (code=exited, status=2)**
** Main PID: 1650 (code=exited, status=2)**

The below controller.hcl file:

# Disable memory lock: mlock(2) - Linux manual page

disable_mlock = true

# Controller configuration block

controller {

# This name attr must be unique across all controller instances if running in HA mode

name = “demo-controller-1”
description = “A controller for a demo!”

# 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://postgres:password123@localhost:5432/boundary?sslmode=disable”

# API listener configuration block

listener “tcp” {

# Should be the address of the NIC that the controller server will be reached on

address = “Controller_IP address ******”

# The purpose of this listener block

purpose = “api”

tls_disable = true

# 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 = [“”, “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 = “Controller_IP address ******”

# The purpose of this listener

purpose = “cluster”

# Root KMS configuration block: this is the root key for Boundary

# Use a production KMS such as AWS KMS in production installs

kms “aead” {
purpose = “root”
aead_type = “aes-gcm”
key = “sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung=”
key_id = “global_root”

# Worker authorization KMS

# Use a production KMS such as AWS KMS for production installs

# This key is the same key used in the worker configuration

kms “aead” {
purpose = “worker-auth”
aead_type = “aes-gcm”
key = “8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=”
key_id = “global_worker-auth”

# Recovery KMS block: configures the recovery key for Boundary

# Use a production KMS such as AWS KMS for production installs

kms “aead” {
purpose = “recovery”
aead_type = “aes-gcm”
key = “8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=”
key_id = “global_recovery”

Can you please help with setting up both controller and worker config files

What does journalctl -u boundary tell you?

There are below errors I can see

Error initializing listener of type tcp: listen tcp :9200: bind: cannot as>

error] failed to initialize database, got error failed to connect to `host=localhost >
internal boundary[1638]: Error connecting to database: unable to create db object with dialect postgres: db.Ope>


It looks like you might have two problems:

  • can’t bind port 9200 (is there already an old Boundary process running on that port?)
  • No Postgres database (did you start a local Postgres before starting Boundary?)

No there is no already existing boundary running on 9200 and there is no Psotgres database initailized prior to the starting of the boundary.

I have attached the controller config file (/etc/boundary.d/boundary.hcl)
controller_hcl file.txt (2.3 KB)

please advise if I need to initialize the postgres DB before starting the controller server.


Yeah, besides the database there’s a few other things you need to set up prior to starting the Boundary controller. I’m guessing you tried to start from the example controller config in the docs – if so, you probably should start from scratch and follow the “getting started with self-managed Boundary” tutorial – it’ll walk you through the prerequisites before you start the controllers.

Also bear in mind that if you just want to get familiar with how Boundary itself works, rather than how to get it up and running, a better place to begin is the “getting started with HCP Boundary” tutorial – you get starter credit when you sign up for the HashiCorp Cloud Platform so you don’t have to spend any money just to run through a few tutorials using HCP.

@omkensey, Is it possible for you to provide the controller and worker config files as per self-hosted worker and controller as mentioned in step 2. I have review config files in hashicorp documentation but still confused with some settings. Thanks