Manage workers
Boundary Community Edition requires organizations to configure their own self-managed workers. Workers can provide access to private networks while still communicating with an upstream Boundary control plane.
Note
Workers should be kept up-to-date with the Boundary control plane's version, otherwise new features will not work as expected.
Boundary is an identity-aware proxy that sits between users and the infrastructure they want to connect to. The proxy has two components:
- A control plane that manages state around users under management, targets, and access policies.
- Worker nodes, assigned by the control plane once a user authenticates into Boundary and selects a target.
Deploying workers allows Boundary users to securely connect to private endpoints (such as SSH services on hosts, databases, or HashiCorp Vault) without exposing a private network.
This tutorial demonstrates the basics of how to register and manage workers using Boundary Boundary Community Edition.
Prerequisites
This tutorial assumes you have:
- Boundary Community Edition running in dev mode
- Completed the previous Community Edition Administration tutorials and created
a
postgrestarget in the Manage Targets tutorial
This tutorial deploys a worker locally in a Docker container, which is then registered to the controller deployed using Boundary's dev mode.
Workers must be able to install the Boundary binary.
To begin, ensure Boundary is running locally in dev mode:
If you restarted dev mode, go back to the Manage Targets tutorial to create a postgres container and target.
Verify the Boundary installation
Verify that Boundary 0.9.0 or above is installed locally.
Configure the worker
To configure a worker, the following details are required:
- Boundary Controller URL (Boundary address)
- Auth Method ID (from the Admin Console)
- Admin login name and password
Because Boundary is running in dev mode, these values map to:
- Boundary Controller URL:
http://127.0.0.1:9200 - Auth Method ID:
ampw_1234567890 - Admin login name and password:
adminandpassword, respectively
Authorization Methods
There are two workflows that can be used to register a worker in Boundary Community Edition:
- Controller-Led authorization workflow
- Worker-Led authorization workflow
Select a workflow to proceed.
In this flow, the operator fetches an activation token from the controller. The token is then embedded in the worker's config file, and authorization is performed when the worker is started.
First, authenticate to the controller. Enter the password of password when
prompted.
Next, generate an activation token for the new worker.
1 2 3 4 5 6 7 8 9 101112131415161718192021222324252627Copy the Controller-Generated Activation Token value on line 6.
Write the worker config
Create a new folder to store your Boundary config file. This tutorial creates
the boundary/ directory in the user's home directory ~/ (labeled as
myusername later on) to store the worker config. If you do not have permission
to create this directory, create the folder elsewhere.
Next, create a new file named worker.hcl in the ~/boundary/
directory.
Open the file with a text editor, such as Vi.
Paste the following configuration into the worker config file:
1 2 3 4 5 6 7 8 9 101112131415Update the <Controller-Generated Activation Token Value> on line 3 with
the token value copied from the boundary workers create controller-led command
output.
Update the auth_storage_path** to match the full path to the
~/boundary/worker1
directory, such as /home/myusername/boundary/worker1.
Notice the listener "tcp" address is set to "127.0.0.1:9204". Because
Boundary is running in dev mode, a pre-configured worker is already
listening on port 9202. To avoid conflicts, the new worker listens on
9204. In a non-dev deployment, the worker would usually listen on
port 9202.
Also notice the worker initial_upstreams is set to 127.0.0.1. In a non-dev
deployment, this address would resolve to an upstream controller.
Save this file.
Parameters that can be specified for workers include:
auth_storage_pathis a local path where a worker will store its credentials. Storage should not be shared between workers.controller_generated_activation_tokenis one-time-use; it is safe to keep it here even after the worker has successfully authorized and authenticated, as it will be unusable at that point.initial_upstreamsindicates the address or addresses a worker will use when initially connecting to Boundary. Do not use any HCP worker values forinitial_upstreams.public_addrattribute can be specified within theworker {}stanza. This example omits the worker's public address because the Boundary client and worker are deployed on the same local machine, but would be used in a non-dev deployment.
To see all valid config options, refer to the worker configuration docs.
Start the worker
With the worker config defined, start the worker server. Provide the full path to the worker config file.
Verify the worker registration
Verify the worker has successfully authenticated to the upstream controller by listing the available workers.
There will be an initial worker created by boundary dev available at
127.0.0.1:9202. The newly created worker will have an address of
127.0.0.1:9204.
Worker management
Workers can be managed and updated using the CLI or Admin Console UI.
List the available workers:
Copy the new worker ID with an Address of 127.0.0.1:9204 (such as
w_O0pSsDWt0U).
Read the worker details:
To update a worker, issue an update request using the worker ID. The request should include the fields to update.
Update the worker name and description:
Updating a worker will return the updated resource details.
Lastly, a worker can be deleted by issuing a delete request using boundary
workers delete and passing the worker ID. To verify deletion, check the worker
no longer exists with boundary workers list.
Note
Do not delete the new worker. Proceed to the next section to test the new worker using an existing target.
Worker-aware targets
From the Manage Targets tutorial you should already have a configured target.
List the available targets:
Export the target ID as an environment variable:
Boundary can use worker tags that define key-value pairs targets can use to determine where they should route connections.
A simple tag was included in the worker.hcl file from before:
This config creates the resulting tags on the worker:
The Tags or Name of the worker (worker1) can be used to create a
worker filter for the target.
Update the postgres target to add a worker tag filter that searches for
workers that have the worker tag. Boundary will consider any worker with this
tag assigned to it an acceptable proxy for this target.
Note
The type: "local" tag could have also been used, or a filter
that searches for the name of the worker directly ("/name" == "worker1").
With the filter assigned, any connections to this target will be forced to proxy through the worker.
Finally, open a session to the postgres target using boundary connect
postgres. When prompted, enter the password secret to connect.
You can verify the session is running through the new worker by checking the worker's active sessions using the CLI or the Admin Console.
Sessions can be managed using the same methods discussed in the Manage Sessions tutorial.
When finished, the session can be terminated manually using \q, or canceled
via another authenticated Boundary command. Sessions can also be managed using
the Admin Console UI or Boundary Desktop app.
Note
To cancel this session using the CLI, you will need to open a new
terminal window and authenticate to Boundary again using boundary
authenticate.
Cancel the existing session.
Cleanup and teardown
Locate the terminal session used to start the
boundary devcommand, and executectrl+cto stop Boundary.Destroy the postgres container created for the tutorial.
Check your work by executing docker ps and ensure there are no more postgres
containers remaining from the tutorial. If unexpected containers still exist,
execute docker rm -f <CONTAINER_ID> against each to remove them.
Summary
The Community Edition Administration tutorial collection demonstrated the common management workflows for a self-managed Boundary deployment.
This tutorial demonstrated worker registration with Boundary Community Edition and discussed worker management.
To continue learning about Boundary, check out the Self-managed access management workflows.