Deploy Boundary using a Helm chart
You can deploy Boundary on Kubernetes with separate Helm charts for the two Boundary runtime resources:
- The Boundary controller chart installs the Boundary control-plane components.
- The Boundary worker chart installs self-managed Boundary data-plane workers.
Boundary uses separate charts for controllers and workers because they have different lifecycle, scaling, persistence, and exposure requirements. The charts use the official hashicorp/boundary-enterprise image by default.
The Boundary Helm charts have been tested and verified to work on Kubernetes versions 1.34 and above. The charts may work with other versions of Kubernetes, but they have not been tested and are not supported.
Boundary architecture
Boundary uses a distributed architecture:
- Controllers manage authentication, authorization, session coordination, worker registration, and API/UI access.
- Workers proxy session traffic between clients, upstream workers, and target systems.
A Boundary controller deployment requires a PostgreSQL database and KMS configuration. A worker deployment requires a valid worker HCL configuration and a registration model. The worker deployment may also need persistent storage, if the selected worker authentication or recording configuration requires it.
Chart resources and models
The charts package Kubernetes resources and Helm release workflows. They do not replace the Boundary runtime configuration.
| Chart | Role | Primary Kubernetes resources | State model |
|---|---|---|---|
| Boundary controller | Control plane | Deployment, services, ConfigMap, ServiceAccount, PodDisruptionBudget, hook jobs | Controller pods are stateless; controller state lives in PostgreSQL. |
| Boundary worker | Data plane | Deployment, services, ConfigMap, PersistentVolumeClaims | PVCs can persist worker identity and optional session recordings. |
Controller chart
The controller chart is intended for operator-managed Boundary control planes on Kubernetes. It can run multiple controller replicas and uses Helm hook Jobs for database initialization. It can also optionally use hook Jobs for database migration, database repair, and admin bootstrap.
You must provide any required external dependencies such as PostgreSQL, KMS access, Boundary Enterprise license data, and TLS material, if necessary.
Worker 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.
Shared configuration model
The Boundary Helm charts separate configuration into two layers:
- Boundary runtime configuration supplied as HCL through a chart value.
- Kubernetes infrastructure configuration supplied through Helm values.
The charts do not infer all runtime settings from the Kubernetes values. You must align listener ports, addresses, storage paths, TLS settings, and registration settings between the Boundary HCL and Kubernetes resources created by the charts.
Next steps
Refer to the following topics for next steps:
- To deploy a controller, refer to Deploy a controller using a Helm chart.
- To deploy workers, refer to Deploy workers using a Helm chart.
More information
- For supported Helm values, refer to the following topics:
- To view example configurations, refer to the following topics: