Worker values

You configure the Boundary worker Helm chart with Helm values and a Boundary HCL configuration. This page documents all Kubernetes values. The chart is the source of truth for supported values.

Boundary runtime configuration

The worker.config contains the Boundary worker HCL. The chart writes this value into a ConfigMap and mounts it at /etc/boundary/boundary-worker.hcl.

The chart renders worker.config with Helm's tpl function. Helm template expressions inside the HCL are evaluated during rendering.

At container startup, the chart replaces ${POD_NAME_LOWER} with the pod name converted to lowercase and starts Boundary with the processed configuration file.

The chart does not fully validate Boundary HCL semantics. It performs targeted checks for the controller-generated activation token reference and operations listener TLS alignment. You are responsible for configuring valid listeners, registration settings, upstreams, storage paths, and worker tags.

Kubernetes infrastructure configuration

Kubernetes-specific values control the Deployment, Services, PVCs, security contexts, and scheduling options. These values do not replace or generate the Boundary runtime HCL.

For example, if you change worker.service.proxy.targetPort to 9222, you must also update the proxy listener port in worker.config.

Refer to the configuration alignment checklist before you finalize any changes.

The following sections describe all available Helm values, grouped by function. Each table lists the key, default value, and a description.

Image values

With both image values empty, the effective Kubernetes image is hashicorp/boundary-enterprise:1.0.2-ent.

Naming and namespace values

By default, resource names use the Helm release name. A release named boundary-worker creates boundary-worker-deployment, boundary-worker-config, boundary-worker-proxy, and boundary-worker-ops.

Worker runtime values

The default worker.config includes disable_mlock = true. The chart's default security model drops all Linux capabilities and disallows privilege escalation. We do not recommend changing this value. Memory locking requires elevated privileges that the chart does not grant. If you enable swap on your nodes, address any resulting data-at-rest exposure through platform controls.

Probe values

The chart adds liveness and readiness probes against /health on the ops listener. The probe scheme is derived from tls.ops.disabled: HTTP when true and HTTPS when false.

Proxy Service values

The chart always renders the proxy Service. It exposes the worker's session traffic listener.

Operations Service values

The chart always renders the operations Service. It exposes the worker operations listener for health and metrics.

Keep the operations Service internal unless a trusted monitoring path requires a different exposure model.

The Deployment declares fixed container ports 9202 and 9203, and its probes use the named ops port at 9203. Keep the ops HCL listener and worker.service.ops.targetPort at 9203. You can change worker.service.ops.port, which is the Service-facing port. A numeric proxy targetPort can route to a different proxy listener, but update both values together.

Operations TLS values

The chart validates the rendered ops listener against tls.ops.disabled. With TLS disabled, the listener must contain tls_disable=true. With TLS enabled, it must not disable TLS and its certificate and key paths must exactly match tls.mountPath. Create the configured Secret before installation. The chart does not verify that the TLS Secret exists or contains the expected keys before the pod is created, and the pod cannot start when the default Secret is absent.

Resource values

Tune resource values for your expected connection volume, recording usage, and cluster sizing.

Auth storage values

Auth storage stores worker identity and authentication material for registration models that require local persistence.

Disable auth storage only when your worker authentication model does not require persistent local auth material, such as KMS-backed worker authentication.

When enabled, the claim is named <fullname>-auth-storage. The chart always mounts the configured path. When you disable persistence, the backing volume is emptyDir.

Recording storage values

Recording storage stores session recordings when recording is configured in Boundary.

If you disable recording storage, remove recording_storage_path from the HCL or ensure recording data does not need to persist.

When enabled, the claim is named <fullname>-recording-storage. The chart requests storage using the configured quantity, access mode, and optional StorageClass. It does not expose PVC selectors or volumeName for explicitly binding a particular pre-provisioned volume. When you disable persistence, the configured recording path is backed by emptyDir.

For either claim, retainOnUninstall=true adds helm.sh/resource-policy: keep. Configuring false omits that annotation. The retention values control Helm deletion during uninstall, not the StorageClass reclaim policy or the underlying PersistentVolume lifecycle.

Secret reference values

The chart injects values from an existing Secret as environment variables into the worker container. Use this to supply sensitive values such as a controller-generated activation token without embedding them in worker.config.

To use a Secret for controller-led registration, set controller_generated_activation_token = "env://BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN" in worker.config and point secretRefs.secretName at the Secret that contains the token key.

When you set secretRefs.secretName, a different env:// name or a hardcoded controller_generated_activation_token fails chart rendering. If the field is absent, the chart neither injects nor validates the Secret. Because validateExisting uses Helm's lookup in the Helm release namespace, use it during an install or upgrade connected to the target cluster and keep namespace aligned with --namespace. Client-only rendering cannot confirm the Secret.

Extra environment variables

Use extraEnv to inject additional environment variables into the worker container. This supports any valid env entry, including plain name/value pairs and valueFrom references.

Example using a plain value:

extraEnv:
  - name: BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN
    value: "act_1234abcd..."

Example using a Secret reference:

extraEnv:
  - name: BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN
    valueFrom:
      secretKeyRef:
        name: boundary-worker-secrets
        key: worker-controller-generated-activation-token

Use extraEnv as an alternative to secretRefs when you need finer control over how Secret keys are mapped to environment variable names, or when injecting variables unrelated to activation tokens.

Extra volumes and manifests

Use the passthrough values to mount additional volumes or render resources with the Helm release.

For example, you can mount an existing ConfigMap and render a NetworkPolicy:

extraVolumes:
  - name: worker-extra-config
    configMap:
      name: worker-extra-config

extraVolumeMounts:
  - name: worker-extra-config
    mountPath: /etc/boundary/extra
    readOnly: true

extraManifests:
  - apiVersion: networking.k8s.io/v1
    kind: NetworkPolicy
    metadata:
      name: '{{ .Release.Name }}-worker'
    spec:
      podSelector:
        matchLabels:
          app.kubernetes.io/instance: '{{ .Release.Name }}'
          app.kubernetes.io/component: worker
      policyTypes:
        - Ingress

Security context values

The default security settings run the worker without elevated privileges.

The Deployment also sets SKIP_SETCAP=1, which prevents the container startup path from attempting Linux capability modification.

ServiceAccount values

Create and annotate any required ServiceAccount separately before installing the chart.

Scheduling values

Configuration alignment checklist

Before installing or upgrading, confirm that:

• The proxy listener port in worker.config matches worker.service.proxy.targetPort.
• The ops listener and worker.service.ops.targetPort remain 9203, and tls.ops.disabled agrees with the listener TLS configuration.
• The auth_storage_path matches worker.persistence.authStorage.path when auth storage is enabled.
• The recording_storage_path matches worker.persistence.recording.path when recording storage is enabled.
• The public_addr matches the endpoint other Boundary clients or workers can actually reach.
• Placeholder activation tokens, cluster IDs, and upstream addresses have been replaced.

Troubleshooting

Worker crash-loops after enabling auth storage

If the worker pod crash-loops after you enable auth storage, confirm that auth_storage_path in worker.config matches the mounted PVC path set by worker.persistence.authStorage.path. A mismatch between the two means the worker cannot read or write its identity material at the expected location.

More information

To view example worker configurations, refer to Worker Helm chart examples.

To install a worker using these values, refer to Deploy workers using a Helm chart.