Elim Tsiagbey
fae2149990
- add docs for local storage states - add docs for `recording_storage_minimum_available_capacity` config field for workers
224 lines
11 KiB
Plaintext
224 lines
11 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: Worker - configuration
|
||
description: |-
|
||
The worker stanza configures worker-specific parameters.
|
||
---
|
||
|
||
# Worker stanza
|
||
|
||
The `worker` stanza configures Boundary worker-specific parameters.
|
||
|
||
All workers within Boundary use certificates and encryption keys to identify
|
||
themselves and protect data in transit. However, there are three different
|
||
ways to register them so that registration of workers can fit into any workflow; controller-led, worker-led, and via external KMS.
|
||
|
||
The differences in how they are configured are in the sub-pages linked at the
|
||
bottom of this page.
|
||
|
||
Workers registered via the worker-led or controller-led methods must be registered in
|
||
the system via an API call, and require storage on disk to store the current set
|
||
of credentials. Workers registering via an external KMS auto-register after successful authentication, making them an easy mechanism to
|
||
use for automatic scaling. This also means they are not required to store
|
||
credentials locally; each time they connect the KMS is used to reauthenticate
|
||
them.
|
||
|
||
~> Prior to version 0.15 of Boundary, there were two different types of workers, PKI & KMS workers.
|
||
If you are using pre-0.15 workers, with pre-0.15 upstreams please be sure to switch the documentation
|
||
version to `0.13.x` - `0.14.x` for correct information.
|
||
|
||
## Common worker parameters
|
||
Regardless of registration mechanism, the following fields are supported.
|
||
|
||
```hcl
|
||
worker {
|
||
public_addr = "5.1.23.198"
|
||
|
||
# Local storage path required if session recording is enabled
|
||
recording_storage_path = "tmp/boundary/"
|
||
|
||
# Minimum available disk space required in the local storage path if session recording is enabled
|
||
recording_storage_minimum_available_capacity = "500MB"
|
||
|
||
# Mutually exclusive with hcp_boundary_cluster_id
|
||
initial_upstreams = [
|
||
"10.0.0.1",
|
||
"10.0.0.2",
|
||
]
|
||
|
||
tags {
|
||
type = ["prod", "webservers"]
|
||
region = ["us-east-1"]
|
||
}
|
||
|
||
# HCP Boundary only
|
||
# hcp_boundary_cluster_id = "....."
|
||
}
|
||
```
|
||
|
||
- `public_addr` - Specifies the public host or IP address (and optionally port)
|
||
at which the worker can be reached _by clients for proxying_. This defaults to
|
||
the address of the listener marked for `proxy` purpose. This is especially
|
||
useful for cloud environments that do not bind a publicly accessible IP to a
|
||
NIC on the host directly, such as an Amazon EIP.
|
||
|
||
This value can reference any of the following:
|
||
- a direct address string
|
||
- a file on disk (file://) from which an address will be read
|
||
- an env var (env://) from which the address will be read
|
||
|
||
- `initial_upstreams` - A list of hosts/IP addresses and optionally ports for
|
||
reaching the boundary cluster. The port will default to `:9201` if not
|
||
specified. This value can be a direct access string array with the addresses,
|
||
or it can refer to a file on disk (`file://`) from which the addresses will be
|
||
read, or an env var (`env://`) from which the addresses will be read. When
|
||
using env or file, their contents must formatted as a JSON array:
|
||
`["127.0.0.1", "192.168.0.1", "10.0.0.1"]`
|
||
|
||
HCP Boundary workers require the [`hcp_boundary_cluster_id`](/boundary/docs/configuration/worker/#hcp_boundary_cluster_id) parameter instead of `initial upstreams`.
|
||
If you configure an HCP worker with `initial_upstreams`, the worker configuration fails.
|
||
|
||
- `hcp_boundary_cluster_id` - A string required to configure workers using worker-led or controller-led registration
|
||
to connect to your HCP Boundary cluster rather than specifying
|
||
`initial_upstreams`. This parameter is currently only valid for workers using the worker-led or controller-led
|
||
registration method and for workers directly connected to HCP Boundary.
|
||
|
||
- `recording_storage_path` - A path to the local storage for recorded sessions.
|
||
Session recordings are stored in the local storage while they are in progress.
|
||
When the session is complete, Boundary moves the local session recording to remote storage and deletes the local copy.
|
||
|
||
- `recording_storage_minimum_available_capacity` - A value measured in bytes that defines the worker's local storage state.
|
||
Boundary compares this value with the available local disk space found in the `recording_storage_path` to determine if a worker can be used for session recording operations.
|
||
The supported suffixes are kb, kib, mb, mib, gb, gib, tb, tib, which are not case sensitive. Example: 2GB, 2gb, 2GiB, 2gib.
|
||
The possible storage states based on the `recording_storage_minimum_available_capacity` are:
|
||
- Available - The worker is above the storage threshold and is available to proxy sessions that are enabled with session recording.
|
||
- Low storage - The worker is below the storage threshold. Existing sessions can continue without interruption, but new sessions that are enabled with session recording cannot be proxied. The worker is not available to record new sessions or play back existing recordings.
|
||
- Critically low storage - The worker is below half the storage threshold. Existing sessions that are enabled with session recording will be forcefully closed. The worker is not available to record new sessions or play back existing recordings.
|
||
- Out of storage - The worker is out of local disk space. It is not available to record new sessions or play back existing recordings. The worker is in a unrecoverable state. An administrator must intervene to remedy the issue.
|
||
- Not configured - The worker does not have a local storage path configured.
|
||
- Unknown - The default local storage state of a worker. This state indicates that the local storage state of a worker is not yet known.
|
||
|
||
- `tags` - A map of key-value pairs where values are an array of strings. Most
|
||
commonly used for [filtering](/boundary/docs/concepts/filtering) targets a
|
||
worker can proxy via [worker
|
||
tags](/boundary/docs/concepts/filtering/worker-tags). On `SIGHUP`, the tags
|
||
set here will be re-parsed and new values used. It can also be a string
|
||
referring to a file on disk (`file://`) or an env var (`env://`).
|
||
|
||
## Signals
|
||
|
||
The `SIGHUP` signal causes a worker to reload its configuration file to pick up any updates for the `initial_upstreams` and `tags` values.
|
||
Any other updated values are ignored.
|
||
|
||
The `SIGTERM` and `SIGINT` signals initiate a graceful shutdown on a worker. The worker waits for any sessions to drain
|
||
before shutting down. Workers in a graceful shutdown state do not receive any new work, including session proxying, from the control plane.
|
||
|
||
## Multi-hop worker capabilities
|
||
|
||
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
|
||
|
||
Multi-hop capabilities, including multi-hop sessions and Vault private access,
|
||
is when a session or Vault credential request goes through more than one worker.
|
||
To enable this, two or more workers must be connected to each other in some
|
||
configuration. There are no limits on the amount of workers allowed in a
|
||
multi-hop session configuration.
|
||
|
||
It helps to think of “upstream” and “downstream” nodes in the context of
|
||
multi-hop. If you view controllers as the “top” node of a multi-hop chain, any
|
||
worker connected to a node is "downstream" of that node; the node that any
|
||
particular worker connects to (whether another worker or a controller) is the
|
||
"upstream" of that node. For example, in the diagram below, Worker 2’s upstream
|
||
is Worker 1, and its downstream is Worker 3.
|
||
|
||
|
||
|
||
You can deploy multi-hop workers in scenarios where inbound network traffic is
|
||
not allowed. A worker in a private network can send outbound communication to
|
||
its upstream worker, and create a reverse proxy to establish a session.
|
||
|
||
You can configure [target worker filters][] with multi-hop workers to allow for
|
||
fine-grained control on which workers handle ingress and egress for session
|
||
traffic to a [target][]. Ingress worker filters determine which workers you
|
||
connect with to initiate a session, and egress worker filters determine which
|
||
workers are used to access targets.
|
||
|
||
### Multi-hop worker requirements
|
||
|
||
When you configure multi-hop sessions, there is an "ingress" worker, an "egress"
|
||
worker, and any number of intermediary workers. Ingress, egress, and
|
||
intermediary workers have the following requirements.
|
||
|
||
#### Ingress worker requirements
|
||
|
||
To proxy target connections, ingress workers require outbound access to the
|
||
Boundary control plane and inbound access from clients.
|
||
|
||
#### Intermediary worker requirements
|
||
|
||
Intermediary workers require outbound access to an upstream worker. The upstream
|
||
worker may be an ingress worker or another intermediary worker. Intermediary
|
||
workers also require inbound access from a downstream worker. The downstream
|
||
worker may be an egress worker or another intermediary worker.
|
||
|
||
#### Egress worker requirements
|
||
|
||
To proxy target connections, egress workers require outbound access to an
|
||
upstream worker and outbound access to the destination host or service.
|
||
|
||
## Complete configuration example
|
||
|
||
```hcl
|
||
listener "tcp" {
|
||
purpose = "proxy"
|
||
tls_disable = true
|
||
address = "127.0.0.1"
|
||
}
|
||
|
||
worker {
|
||
# Path for worker storage, assuming worker-led or controller-led registration. Must be unique across workers
|
||
auth_storage_path="/boundary/demo-worker-1"
|
||
|
||
# Local storage path required if session recording is enabled
|
||
recording_storage_path = "tmp/boundary/"
|
||
|
||
# Minimum available disk space required in the local storage path if session recording is enabled
|
||
recording_storage_minimum_available_capacity = "500MB"
|
||
|
||
# Workers typically need to reach upstreams on :9201
|
||
initial_upstreams = [
|
||
"10.0.0.1",
|
||
"10.0.0.2",
|
||
"10.0.0.3",
|
||
]
|
||
|
||
public_addr = "myhost.mycompany.com"
|
||
|
||
tags {
|
||
type = ["prod", "webservers"]
|
||
region = ["us-east-1"]
|
||
}
|
||
}
|
||
|
||
# The following KMS config is an example only
|
||
# Use a production KMS such as AWS KMS for production installs
|
||
kms "aead" {
|
||
purpose = "worker-auth-storage"
|
||
aead_type = "aes-gcm"
|
||
key = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
|
||
key_id = "worker-auth-storage"
|
||
}
|
||
|
||
|
||
```
|
||
|
||
## Tutorials
|
||
|
||
Refer to the [Self-Managed Worker Registration with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-workers) tutorial to learn how to register and manage Workers.
|
||
|
||
Refer to the [Manage Multi-Hop Sessions with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-multi-hop) tutorial to learn how to configure a multi-hop session.
|
||
|
||
[Worker Configuration Methods]: /boundary/docs/configuration/worker/worker-configuration
|
||
[target]: /boundary/docs/concepts/domain-model/targets
|
||
[target worker filters]: /boundary/docs/concepts/filtering/worker-tags#target-worker-filtering
|
||
[session recording]: /boundary/docs/configuration/session-recording
|