Deploying HashiCorp Boundary on Kubernetes has, until now, required teams to build and maintain their own orchestration from scratch. That means hand-crafting deployments, services, config maps, and lifecycle automation for every environment, then keeping it all consistent over time.
To officially support Boundary deployed on Kubernetes, we have released two official Helm charts: one for the Boundary controller and one for the Boundary worker. Together, they provide a standardized, repeatable, and production-ready path for deploying Boundary's control plane and data plane.
Whether you operate a fully self-managed Boundary cluster or run HCP Boundary with self-managed workers in your own infrastructure, these charts reduce operational overhead and bring the deployment experience in line with how teams already manage Kubernetes workloads.
Which chart do I need?
Self-managed Boundary customers deploy and operate the entire Boundary stack themselves. These customers will use both charts: the controller chart to stand up the control plane, and the worker chart to deploy the workers that proxy sessions to target resources.
HCP Boundary customers have their Boundary controllers and a pair of ingress workers managed on the HashiCorp Cloud Platform. However, reaching private resources inside their own networks requires deploying self-managed workers in their network. These customers will use the worker chart to deploy those workers on Kubernetes.
»The controller Helm chart
The controller is the brain of a Boundary deployment, handling authentication, authorization, and session brokering. For self-managed customers, deploying the controller on Kubernetes has historically meant assembling deployments, services, database initialization scripts, and upgrading automation from scratch. The controller Helm chart packages all for ease of use.
On first deployment, the chart automates the steps that typically require the most manual coordination. Boundary's HCL configuration is rendered through a templated config map, and all sensitive values (database credentials, license keys, KMS references) are resolved at runtime from Kubernetes secrets via Boundary's native env:// interpolation. The chart never manages raw secrets, instead consuming pre-existing secrets provisioned by operators or synced by tools like Vault Secrets Operator. A pre-install Helm hook handles database schema initialization automatically, so the controller is ready to accept connections as soon as the pod is healthy.
For Day 2 operations, the chart is built around safe upgrades and operational visibility. Database migrations are handled through a dedicated pre-upgrade hook that is disabled by default, requiring an explicit opt-in flag to prevent accidental schema changes. Readiness probes against Boundary's /health endpoint gate rolling updates, so new pods must be healthy before old ones terminate. SHA256 checksum annotations on the deployment automatically trigger restarts when configuration or values change, preventing drift between desired and running state.
For production resilience, the chart supports multiple controller replicas distributed across availability zones with pod anti-affinity rules and pod disruption budgets, ensuring controllers remain available during node maintenance and cluster upgrades.
»The worker Helm chart
Workers are the data-plane component of Boundary. They register with the controller, receive session assignments, and proxy all traffic between clients and target systems. In HCP Boundary deployments, self-managed workers are how organizations extend the data plane into their own private networks to reach internal resources. In self-managed deployments, workers complete the connection path from authenticated clients to target infrastructure. The worker Helm chart packages this workload for Kubernetes with the same declarative approach.
The chart deploys a worker with either egress capabilities (connecting outbound to target systems) or intermediate capabilities (relaying traffic across network boundaries for multi-hop topologies). After the pod starts, the worker must register with the control plane before it can proxy sessions. The chart supports all of Boundary's registration models: controller-led, where the operator pre-creates a worker resource and supplies an activation token in the HCL configuration; worker-led, where the worker generates its identity at startup and outputs a registration token in the pod logs for the operator to register manually; and KMS-led, where workers authenticate using a shared KMS key configured in both the controller and worker.
Regardless of registration model, the worker's identity and authentication material are written to a persistent volume claim, so the worker does not need to re-register after a restart or rescheduling event. When session recording is enabled, the chart provisions a second PVC, so that recorded session data persists durably alongside the worker's identity storage.
Upgrades follow standard Helm workflows. Updating the container image tag and running helm upgrade restarts the worker pod while preserving all persistent states. The chart configures a termination grace period that allows active sessions to drain before the pod is stopped, preventing disruption to in-progress connections.
Getting started
Both charts are published as Open Container Initiative (OCI) artifacts and can be installed using Helm 3. The following is an abbreviated quickstart to get you up and running. For complete step-by-step instructions, prerequisites, and environment-specific configuration, refer to the deployment guide in each chart repository.
»Deploy a Boundary controller with controller helm chart (self-managed)
Before installing, ensure you have a reachable PostgreSQL database, KMS keys provisioned for root, recovery, and worker-auth purposes, and the required Kubernetes secrets created in your target namespace for the database connection URL, enterprise license, TLS certificates, and admin credentials.
# Install the controller chart
helm install boundary-controller oci://<chart-url>/boundary-controller \
--namespace boundary \
--values values.yaml
# Create the namespace
kubectl create namespace boundary
# Install the controller chart
helm install boundary-controller oci://<chart-url>/boundary-controller \
--namespace boundary \
--values values.yaml The controller chart handles database initialization automatically on first install. After installation, verify the controller pods are running and healthy:
kubectl get pods -n boundary If you enable admin bootstrapping, you could authenticate immediately using the credentials stored in your Kubernetes secrets.
»Deploy a Boundary worker (HCP or self-managed)
Before installing, prepare your worker HCL configuration file with the appropriate upstream controller addresses, tags, and registration token (if using controller-led registration).
# Create the namespace (if not already created)
kubectl create namespace boundary
# Install the worker chart
helm install boundary-worker oci://<chart-url>/boundary-worker \
--namespace boundary \
--set-file worker.config=/path/to/worker.hcl After installation, verify the worker pod is running and check the logs to confirm successful registration with the control plane:
kubectl get pods -n boundary
kubectl logs -n boundary deployment/boundary-worker For intermediate workers, retrieve the load balancer's external address, update public_addr in your worker config, and apply the change with a Helm upgrade:
helm upgrade boundary-worker oci://<chart-url>/boundary-worker \
--namespace boundary \
--reuse-values \
--set-file worker.config=/path/to/worker.hcl »A note on upgrades
Both charts support standard Helm upgrade and rollback workflows. For the worker chart, updating the container image tag in your values and running a Helm upgrade restarts the worker pod while preserving persistent state. Active sessions are allowed to drain within the configured termination grace period.
For the controller chart, configuration changes trigger a rolling update automatically. Database migrations require an explicit opt-in flag (--set controller.database.migrate.enabled=true) and should be preceded by a full database backup, as Boundary schema migrations are one-way operations.
»Conclusion
These Helm charts bring Boundary deployments in line with how teams already operate infrastructure on Kubernetes. Self-managed customers get a production-ready path for the full Boundary stack, while HCP Boundary customers get a streamlined way to extend their data plane into private networks.
Both charts are available now. Visit the worker chart and controller chart repositories on GitHub to review the source, values reference, and deployment guides. If you are new to Boundary, the self-managed deployment documentation and HCP Boundary getting started guide provide the foundation you need before deploying with Helm.
To learn more about Boundary or get started with HCP Boundary, visit hashicorp.com/boundary.
