Worker values

You configure the Boundary worker Helm chart with Helm values and a Boundary HCL configuration. This page documents the Helm values you use to deploy the worker on Red Hat OpenShift, including the shared chart values and the OpenShift-specific 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.

OpenShift infrastructure configuration

OpenShift-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 and openshift.enabled=true, the effective image is registry.connect.redhat.com/hashicorp/boundary-enterprise:1.0.2-ent-ubi.

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

OpenShift values

Set openshift.enabled=true to render OpenShift Routes, use security contexts that let a security context constraint (SCC) assign user and group IDs, and select the Red Hat certified image defaults. OpenShift mode does not change the configured Service types. Refer to the OpenShift worker examples for complete configurations.

OpenShift image resolution

OpenShift mode changes the resolved image only when you leave the corresponding image value empty.

The Red Hat registry requires authentication. Reference a pull Secret in imagePullSecrets, or link one to the ServiceAccount used by the worker.

OpenShift security context values

When openshift.enabled=true, these values replace the shared podSecurityContext and containerSecurityContext on the worker Deployment.

The values omit runAsUser, runAsGroup, and fsGroup so that the project's SCC can assign IDs from its allowed range. The defaults are compatible with the restricted-v2 SCC and do not require elevated privileges. Do not pin an ID unless the ServiceAccount uses an SCC that permits it.

Proxy Route values

The proxy Route exposes Boundary session traffic through the OpenShift router.

The chart fixes proxy Route termination to passthrough because the proxy listener carries Boundary session TLS over TCP. Clients connect to the router on port 443, not the Service port 9202. Set public_addr in worker.config to <PROXY_ROUTE_HOST>:443.

Operations Route values

The operations Route exposes the worker health and metrics endpoint through the OpenShift router.

The default pairing is reencrypt termination with tls.ops.disabled=false. The router serves client-facing TLS and creates a separate TLS connection to the worker. Create the boundary-worker-tls Secret with tls.crt and tls.key, keep the operations listener certificate paths aligned with /etc/boundary/tls, and set destinationCACertificate to the CA that issued the backend certificate.

The destination CA verifies the router-to-worker connection. The key, certificate, and caCertificate fields customize the separate client-facing certificate. Avoid exposing health and metrics endpoints unless a trusted monitoring path requires the Route.

For edge termination, set tls.ops.disabled=true so the router forwards HTTP to the worker. For passthrough, keep operations TLS enabled because the worker terminates the client TLS connection. The chart only renders destinationCACertificate for reencrypt when operations TLS is enabled. Probes connect directly to the pod and derive HTTP or HTTPS behavior from tls.ops.disabled. They do not pass through the Route.

Service type caveat

Routes add ingress paths to Services. They do not replace Services or change their types. The proxy Service remains LoadBalancer by default even when you enable the proxy Route. Set worker.service.proxy.type=ClusterIP when you want the Route to be the only external proxy path. Otherwise, the chart creates both the Route and the configured external Service. The operations Service defaults to ClusterIP.

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.

On OpenShift, also confirm the following settings:

• Set openshift.enabled=true.
• Decide whether each Route is required, and set exposed Services to ClusterIP unless you also want their configured external Service path.
• Use <PROXY_ROUTE_HOST>:443 as public_addr when clients connect through the proxy Route.
• Keep the proxy Route on its fixed passthrough termination.
• Align tls.ops.disabled, operations listener TLS, and the operations Route termination mode. Provide a destination CA certificate for reencrypt.
• Confirm that the project's storage classes and SCC permit the volumes when you enable persistent storage.
• Confirm that referenced Secrets contain the required keys.
• Confirm that the ServiceAccount can pull the Red Hat image and that its SCC admits the OpenShift security contexts.
• Check project ResourceQuota and LimitRange policies for the worker Deployment and persistent volume claims.

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.

Worker pods fail admission

An unable to validate against any security context constraint error means the pod requests settings that no SCC allows. Confirm that openshift.enabled=true, remove pinned runAsUser, runAsGroup, and fsGroup values, and verify the SCC assigned to the worker ServiceAccount.

Worker image pulls fail

Confirm that the pull Secret contains credentials for registry.connect.redhat.com and is present in imagePullSecrets or linked to the worker ServiceAccount. An explicit image.repository or image.tag overrides the Red Hat defaults.

Clients cannot reach the proxy Route

Confirm that public_addr uses the proxy Route hostname and port 443, not port 9202. Verify that the Route uses its fixed passthrough termination and inspect it with oc describe route ROUTE_NAME --namespace PROJECT_NAME.

Operations Route returns TLS errors

For the default reencrypt mode, confirm that the worker operations listener serves HTTPS with tls.ops.disabled=false and provide the backend certificate's issuing CA in openshift.route.ops.tls.destinationCACertificate. If you use edge, set tls.ops.disabled=true so the backend serves HTTP.

Worker fails after enabling storage

Confirm that auth_storage_path and recording_storage_path in worker.config match the chart mount paths. Check persistent volume claim events for storage class, quota, and SCC errors.

More information

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

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