Deploy workers using a Helm chart

The worker chart installs one self-managed Boundary worker per Helm release. It is focused on egress and intermediate worker use cases, including workers used with HCP Boundary or self-managed Boundary deployments.

The worker chart mounts the worker HCL you provide in worker.config, exposes optional proxy and operations services, and provisions optional PVCs for auth storage and session recording storage.

Deploying the Boundary worker Helm chart gives you a running data plane worker that registers with a controller or HCP (HashiCorp Cloud Platform) Boundary and is ready to proxy session traffic to your targets. The baseline configuration on this page deploys a KMS-authenticated worker for a self-managed Boundary control plane. This page covers installing the worker chart only. To stand up the control plane first, refer to Deploy controllers using a Helm chart.

Prerequisites

Before installing the worker Helm chart, make sure the following are available:

• A Kubernetes cluster running version 1.34 or later.
• Helm 3 or later configured with access to the target Kubernetes cluster.
• Network connectivity from the worker pod to the HCP (HashiCorp Cloud Platform) Boundary cluster or self-managed Boundary upstream workers.
• A valid Boundary worker HCL configuration.
• A TLS certificate and private key for the operations listener.
• A default StorageClass or pre-provisioned PersistentVolumes when you enable persistent auth storage or session recording storage.
• A registration model selected before installation:

Token-based registration requires persistent auth storage so that the worker retains its credentials across pod restarts. KMS-backed worker authentication does not require persistent auth storage. Intermediate workers may also require a reachable endpoint for the proxy listener and cluster support for the selected Service type, such as LoadBalancer.

Add the HashiCorp Helm repository

Add the Helm repository and confirm the chart is visible:

$ helm repo add hashicorp https://helm.releases.hashicorp.com
$ helm repo update
$ helm search repo hashicorp/boundary-worker --versions

Refer to the Boundary worker chart on Artifact Hub for official releases and default chart values. Choose a chart version compatible with your HCP Boundary or self-managed control plane. Refer to Control plane and worker compatibility. To pin the chart version, add --version <chart-version> to the helm install and helm upgrade commands.

Prepare the worker configuration

The chart reads raw Boundary HCL from worker.config. Embed the HCL inline in a values file under the worker.config key and pass the file with --values.

For a base worker configuration, refer to the worker configuration guidance in the Create the worker configuration reference.

A usable worker configuration includes:

• A proxy listener for session traffic
• An operations listener for health and metrics
• A worker registration mechanism
• An hcp_boundary_cluster_id for HCP Boundary or initial_upstreams for an upstream worker or controller
• An auth_storage_path when auth storage persistence is enabled
• A recording_storage_path when session recording persistence is enabled
• A public_addr when other clients or workers must connect to this worker

The chart enables TLS for the operations listener by default with tls.ops.disabled=false. It mounts the existing boundary-worker-tls Secret at tls.mountPath. The HCL must use the templated TLS value and certificate paths shown in the following example. Chart validation rejects tls_disable=true unless you also set tls.ops.disabled=true.

The proxy and operations Services always render. By default, the proxy Service uses LoadBalancer, and the operations Service uses ClusterIP. Keep the operations listener and Service target port at 9203 because the deployment uses the named ops container port for health probes.

Refer to the following example self-managed KMS worker configuration:

disable_mlock = true

listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

listener "tcp" {
  address       = "0.0.0.0:9203"
  purpose       = "ops"
  tls_disable   = "{{ .Values.tls.ops.disabled }}"
  tls_cert_file = "{{ .Values.tls.mountPath }}/tls.crt"
  tls_key_file  = "{{ .Values.tls.mountPath }}/tls.key"
}

worker {
  name = "boundary-worker"
  public_addr = ""
  initial_upstreams = ["boundary-controller-cluster:9201"]

  tags {
    type = ["worker", "egress"]
  }
}

kms "aead" {
  purpose = "worker-auth"
  aead_type = "aes-gcm"
  key = "REPLACE_WITH_BASE64_ENCODED_32_BYTE_KEY"
  key_id = "global_worker-auth"
}

events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enabled = true
  sink "stderr" {
    name        = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format      = "cloudevents-json"
  }
}

Install a Boundary worker

Create a file named worker-values.yaml that contains worker.config and any Kubernetes overrides. Replace REPLACE_WITH_BASE64_ENCODED_32_BYTE_KEY with the worker-auth key configured on your controllers:

tls:
  ops:
    disabled: false
  secretName: boundary-worker-tls
  mountPath: /etc/boundary/tls

worker:
  config: |
    disable_mlock = true

    listener "tcp" {
      address = "0.0.0.0:9202"
      purpose = "proxy"
    }

    listener "tcp" {
      address       = "0.0.0.0:9203"
      purpose       = "ops"
      tls_disable   = "{{ .Values.tls.ops.disabled }}"
      tls_cert_file = "{{ .Values.tls.mountPath }}/tls.crt"
      tls_key_file  = "{{ .Values.tls.mountPath }}/tls.key"
    }

    worker {
      name = "boundary-worker"
      public_addr = ""
      initial_upstreams = ["boundary-controller-cluster:9201"]

      tags {
        type = ["worker", "egress"]
      }
    }

    kms "aead" {
      purpose = "worker-auth"
      aead_type = "aes-gcm"
      key = "REPLACE_WITH_BASE64_ENCODED_32_BYTE_KEY"
      key_id = "global_worker-auth"
    }

    events {
      audit_enabled        = true
      sysevents_enabled    = true
      observations_enabled = true
      sink "stderr" {
        name        = "all-events"
        description = "All events sent to stderr"
        event_types = ["*"]
        format      = "cloudevents-json"
      }
    }

Create the namespace and the TLS Secret before you install the release. The certificate must be valid for the address clients use to reach the operations listener:

$ kubectl create namespace boundary
$ kubectl create secret tls boundary-worker-tls \
  --namespace boundary \
  --cert=worker.crt \
  --key=worker.key

Run the following command to install the release:

$ helm install boundary-worker hashicorp/boundary-worker \
  --namespace boundary \
  --values worker-values.yaml \
  --wait

Example output:

NAME: boundary-worker
LAST DEPLOYED: Tue Jul 22 00:00:00 2026
NAMESPACE: boundary
STATUS: deployed
REVISION: 1

Verify the deployment

Check the rendered resources after installation:

$ kubectl get deployment,pods,svc --namespace boundary; \
  kubectl logs --namespace boundary deployment/boundary-worker-deployment

Example output:

NAME                                          READY   STATUS    RESTARTS   AGE
pod/boundary-worker-deployment-abcde          1/1     Running   0          2m
 
NAME                            TYPE           CLUSTER-IP   EXTERNAL-IP   PORT(S)          AGE
service/boundary-worker-proxy   LoadBalancer   10.0.0.20    203.0.113.9   9202:31500/TCP   2m
service/boundary-worker-ops     ClusterIP      10.0.0.21            9203/TCP         2m

Confirm that:

• The pod becomes Ready.
• The proxy and ops Services match your intended exposure model.
• Worker logs show successful registration or authentication.
• The worker appears as active in Boundary and is eligible for session assignment.

The baseline KMS configuration does not enable auth or recording persistence, so it does not create PersistentVolumeClaims. When you enable auth or recording persistence, confirm that the boundary-worker-auth-storage or boundary-worker-recording-storage claim is Bound.

Update public_addr for workers

Kubernetes may assign the external hostname or IP after installation when worker.service.proxy.type is LoadBalancer. If worker.service.proxy.type is ClusterIP, use a cluster-reachable address when the worker is accessed internally.

Use the following command to watch the proxy Service:

$ kubectl get svc boundary-worker-proxy --namespace boundary --watch

If the worker HCL needs the final address, update the public_addr field in worker.config or in the HCL file with the LoadBalancer address or internal ClusterIP address, then upgrade the release:

$ helm upgrade boundary-worker hashicorp/boundary-worker \
  --namespace boundary \
  --values worker-values.yaml \
  --rollback-on-failure \
  --wait

Uninstall the worker

To remove the worker Helm release and its associated Kubernetes resources, run:

$ helm uninstall boundary-worker --namespace boundary

Troubleshooting

Worker does not become active

If the worker does not appear as active in Boundary after installation, confirm that initial_upstreams in worker.config points to the correct controller cluster address (or hcp_boundary_cluster_id for HCP Boundary). A worker configured with the wrong upstream address cannot complete registration and remains stuck in a non-active state.

More information

• To view supported Helm values so that you can configure or update workers, refer to Worker values.
• To view example configurations, refer to Worker Helm chart examples.