Controller values

• Boundary runtime configuration
• Kubernetes infrastructure configuration
• Naming and namespace values
• Image values
• TLS values
• Secret reference values
• Controller runtime values
• Listener Service values
• Probe values
• Resource values
• Database job values
• Bootstrap admin values
• Extra environment variables
• Security context values
• ServiceAccount values
• Availability and shutdown values
• Scheduling values
• Configuration alignment checklist

The Boundary controller Helm chart is configured with Helm values and a user-provided Boundary HCL configuration. 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 validate Boundary controller semantics beyond a few chart-level alignment checks. You are responsible for configuring valid listeners, database settings, cluster addresses, KMS stanzas, rate limits, and event sinks.

The chart validates the following:

• The tls_cert_file and tls_key_file settings are aligned with tls.mountPath when tls.disabled=false.
• AEAD KMS keys are not referenced through env://BOUNDARY_KMS_* inside kms blocks.
• Required Secret keys exist when secretRefs.validateExisting=true.

Kubernetes infrastructure configuration

Kubernetes-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

When you enable TLS, keep the listener tls_cert_file and tls_key_file paths in controller.config aligned with tls.mountPath. Probe schemes are auto-derived from tls.disabled and do not need to be set manually.

Secret reference values

The secretRefs.keys values are the key names inside your Kubernetes Secret — they are not fixed by the chart. Set each to match the actual key name you used when creating the Secret. For example, if you created the Secret with --from-literal=pg-url=..., set secretRefs.keys.databaseUrl: "pg-url".

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 automatically adds liveness and readiness probes when an ops TCP listener is defined in controller.config. You do not need to set these values unless you want to adjust probe timing. The probe scheme is auto-derived from tls.disabled: HTTPS when tls.disabled=false, HTTP when tls.disabled=true. Override per-probe with controller.livenessProbe.scheme or controller.readinessProbe.scheme if needed.

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 is idempotent. If the database is already initialized, the Job exits successfully.

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

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

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.
• The tls_cert_file and tls_key_file settings match tls.mountPath when TLS is enabled.
• Probe schemes are auto-derived from tls.disabled. Override only if the derived scheme does not match your listener configuration.
• 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.

More information

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