Controller values

You configure the Boundary controller Helm chart with Helm values and a Boundary HCL configuration. This page documents the Helm values you use to deploy the controller 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 controller.config contains the Boundary controller HCL. The chart writes the HCL values into a ConfigMap and mounts it at /etc/boundary/controller.hcl.

The chart does not fully validate Boundary controller semantics. You are responsible for configuring valid listeners, database settings, cluster addresses, key management system (KMS) stanzas, rate limits, and event sinks.

The chart performs these targeted checks:

• An API listener exists. An operations listener also exists when tls.ops.disabled=false.
• API and operations listener tls_disable settings align with tls.api.disabled and tls.ops.disabled.
• TLS-enabled API and operations listeners use tls_cert_file and tls_key_file paths under tls.mountPath.
• Authenticated Encryption with Associated Data (AEAD) key management system (KMS) keys do not use unsupported env://BOUNDARY_KMS_* references.
• Secret-backed database, migration, and license fields use the chart's environment variable names or names declared in extraEnv.
• The referenced Secret contains the keys required by the rendered configuration and enabled bootstrap Job when secretRefs.validateExisting=true.
• Database migrations run with controller.replicas=0, and a repair version is set only when migration is enabled.

OpenShift infrastructure configuration

OpenShift-specific values control the Deployment, Services, ConfigMap, Job hooks, security contexts, ServiceAccount, and scheduling options. These values do not replace or generate the Boundary runtime HCL.

For example, if you change controller.service.api.targetPort to 9220, you must also update the API listener port in the controller.config.

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

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

Naming and namespace values

Image values

TLS values

You can configure API and operations TLS independently. The chart mounts the TLS Secret when either listener has TLS enabled. Keep each listener's tls_disable setting aligned with its corresponding chart value and keep certificate paths aligned with tls.mountPath. The chart checks the paths but does not validate certificate contents, trust, expiration, or subject alternative names (SANs).

Secret reference values

The secretRefs.keys values are key names inside your Secret. The chart mounts no Secret as a file. Instead, it conditionally creates environment variables from Secret key references when the rendered HCL uses env://BOUNDARY_PG_URL, env://BOUNDARY_PG_MIGRATION_URL, or env://BOUNDARY_LICENSE. The bootstrap Job always references the administrator keys when enabled.

Validation is targeted. With secretRefs.validateExisting=true, the chart checks only the keys used by the rendered configuration and enabled bootstrap settings. With the default false, a missing Secret or key is reported when the pod is created. Neither mode validates the values or external service connectivity.

Controller runtime values

The default controller.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.

Listener Service values

The chart creates separate Services for the API, cluster, and ops listeners.

API Service values

Cluster Service values

Ops Service values

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

Probe values

The chart always renders HTTP GET liveness and readiness probes for /health on the named ops container port. The chart derives the scheme from tls.ops.disabled: HTTPS when false and HTTP when true. The probe scheme is not exposed as a value. The probes are not conditional on parsing an operations listener from HCL.

Resource values

Tune resource values for your expected API load, worker volume, session coordination, and audit event volume.

Database job values

The chart uses hook Jobs for database initialization, migration, and optional repair.

The initialization Job runs only on install and is enabled by default. Disable it when another workflow manages database initialization. Migration and repair are pre-upgrade hooks. Enabling migration requires controller.replicas=0. Setting a repair version requires you to enable migration. When you set both values, Helm runs repair first at hook weight -10 and migration at hook weight -5.

Bootstrap admin values

The bootstrap admin Job creates or updates a global password auth method, user, account, and role using Boundary recovery privileges.

Disable this Job if you already manage Boundary auth methods and admin principals outside the chart.

Extra environment variables

Extra volume and manifest values

The chart renders each supported extraManifests entry as a separate YAML document. Helm applies these resources as part of the release, but the chart does not otherwise validate or modify them.

Security context values

The default security settings run the controller without elevated privileges.

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

ServiceAccount values

Availability and shutdown values

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. The OpenShift security contexts apply to the controller Deployment and all hook Jobs.

The chart evaluates the remaining values under openshift only when OpenShift mode is enabled.

OpenShift image resolution

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

The Red Hat registry requires authentication. Reference a pull Secret in the shared imagePullSecrets value, or link one to the ServiceAccount used by the controller. The shared image.pullPolicy behavior does not change in OpenShift mode.

OpenShift security context values

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

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.

API Route values

For edge termination, set tls.api.disabled=true. For reencrypt or passthrough, set tls.api.disabled=false. For reencrypt, also set destinationCACertificate to the certificate authority (CA) that issued the controller certificate. Helm rendering fails when the Route termination and listener TLS setting do not match these requirements.

The key, certificate, and caCertificate fields configure the certificate that the OpenShift router presents to API clients for edge and re-encrypt Routes. They are distinct from destinationCACertificate, which lets the router verify the controller's backend certificate for re-encrypt termination. When the client-facing fields are empty, the Route uses the ingress controller's default certificate.

Cluster Route values

The chart fixes cluster Route termination to passthrough because the listener carries Boundary mutual TLS over TCP. External workers connect to the router on port 443, not the Service port 9201. Set the controller's advertised public_cluster_addr to <ROUTE_HOST>:443 when workers use this Route.

Ops Route values

For edge termination, set tls.ops.disabled=true. For reencrypt or passthrough, set tls.ops.disabled=false. Helm rendering fails when the Route termination and listener TLS setting do not match these requirements. Avoid exposing health and metrics endpoints unless a trusted monitoring path requires the Route.

The ops key, certificate, and caCertificate fields have the same client-facing behavior as their API Route counterparts. The chart omits them for passthrough termination because the router does not terminate the client TLS connection. For reencrypt termination, destinationCACertificate verifies the operations listener's backend certificate.

Service type caveat

Routes add ingress paths to Services. The Routes do not replace Services or change their types. The API Service remains LoadBalancer by default even when you enable the API Route. Set controller.service.api.type=ClusterIP when you want the Route to be the only external API path. The cluster and operations Services default to ClusterIP.

Configuration alignment checklist

Before installing or upgrading a controller, confirm that:

• The API listener port in controller.config matches controller.service.api.targetPort.
• The cluster listener port in controller.config matches controller.service.cluster.targetPort.
• The ops listener port in controller.config matches controller.service.ops.targetPort.
• The public_cluster_addr setting matches the endpoint workers can actually reach.
• Each listener's tls_disable setting matches tls.api.disabled or tls.ops.disabled, and enabled listeners use certificate paths under tls.mountPath.
• The probe scheme derived from tls.ops.disabled matches the operations listener.
• The referenced Secret contains every key required by the current controller.config and bootstrap settings.
• The terminationGracePeriodSeconds setting exceeds graceful_shutdown_wait_duration in the controller HCL.

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 <CLUSTER_ROUTE_HOST>:443 as public_cluster_addr for workers that connect through the cluster Route.
• Align API and operations listener TLS with each Route termination mode and provide destination CA certificates for reencrypt Routes.
• 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 Deployment and hook Jobs.

Troubleshooting

Controller pods fail readiness or liveness probes

If controller pods fail readiness or liveness probes after you change TLS settings, confirm that the operations listener exists on controller.service.ops.targetPort. Also confirm that its TLS setting matches tls.ops.disabled. Both probe schemes derive from tls.ops.disabled.

Controller 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 controller ServiceAccount.

Controller image pulls fail

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

Routes return TLS errors

Confirm that listener TLS matches the Route termination mode. For reencrypt, verify that destinationCACertificate contains the CA that issued the backend certificate. Inspect the Route with oc describe route ROUTE_NAME --namespace PROJECT_NAME.

Workers cannot register through the cluster Route

Confirm that the cluster Route is enabled, uses its fixed passthrough termination, and is reachable on port 443. Set public_cluster_addr to the Route hostname and port 443.

More information

To view example controller configurations, refer to Controller OpenShift Helm chart examples.

To install a controller using these values, refer to Deploy controllers on OpenShift using a Helm chart.