Effortless Deployment of HashiCorp Boundary on Kubernetes with New Helm Charts

Deploying HashiCorp Boundary on Kubernetes has been a considerable challenge for teams, requiring the assembly of individual components like deployments and services, as well as lifecycle management. The introduction of official Helm charts for Boundary aims to standardize this process, providing a well-defined, repeatable pathway for setting up both the control and data planes of Boundary.

The two newly released Helm charts serve distinct functions: one for the Boundary controller and another for the Boundary worker. These charts are designed to streamline operations, making it easier for organizations to incorporate Boundary into their Kubernetes ecosystem.

Understanding the Use Cases

For self-managed Boundary users, both Helm charts are necessary. The controller chart sets up the control plane, while the worker chart handles session proxying to various target resources. On the other hand, customers utilizing HashiCorp Cloud Platform (HCP) Boundary have their controllers managed by HashiCorp, but they will still need to deploy self-managed workers in their own networks for access to private resources. Thus, they will utilize the worker Helm chart only.

The Controller Helm Chart Features

The controller functions as the central hub in a Boundary deployment, overseeing authentication, authorization, and session management. Historically, self-managed customers had to build out their Kubernetes deployments for the controller from scratch, a process that was both complex and error-prone. The new controller Helm chart simplifies this setup by packaging all necessary components, making deployment significantly more straightforward.

On the initial deployment, the chart automates steps that usually would require careful manual input. It uses HCL configuration rendered through a templated config map, ensuring sensitive information like database credentials and license keys is managed securely via Kubernetes secrets, rather than directly within the Helm chart. A pre-install hook automatically sets up the database schema, allowing for immediate connections once the pod is healthy.

For ongoing operations, the chart prioritizes safe upgrades and transparent operational management. It includes dedicated hooks for database migrations, which are disabled by default, prompting operators to opt-in intentionally for any schema changes. Readiness probes linked to Boundary's health endpoint ensure that rolling updates occur only when new pods are fully functional. The deployment also implements SHA256 checksum annotations to trigger restarts automatically if configuration changes occur, eliminating drift between the desired and actual states.

For resilience, the controller Helm chart supports the deployment of multiple controller replicas distributed across availability zones, incorporating pod anti-affinity rules and disruption budgets to maintain availability during maintenance operations or cluster upgrades.

The Worker Helm Chart Considerations

The worker component represents the data plane of Boundary, responsible for registering with the controller, receiving session assignments, and proxying traffic between clients and target systems. In deployments using HCP Boundary, self-managed workers are essential for bridging the data plane into the organization’s private networks. For self-managed environments, the workers ensure connectivity from authenticated clients to targeted infrastructure.

The Helm chart for workers utilizes a similar declarative approach, allowing for easy deployment. It supports various registration models, including controller-led, worker-led, and KMS-led registrations. After deployment, the worker must register with the control plane before proceeding with session proxying.

Worker identity and authentication particulars are securely stored in a Persistent Volume Claim (PVC), enabling continuity after restarts or rescheduling—an important feature for maintaining connection stability. If session recording is activated, the chart provisions an additional PVC for the recorded session data to ensure durability alongside the worker's identity information.

Upgrading the worker follows standard Helm workflows. When updating the container image, executing a Helm upgrade preserves persistent state while allowing active sessions to complete. The chart is configured with a termination grace period to minimize disruption to ongoing connections.

Getting Started with Helm Charts

Both the controller and worker charts are published as Open Container Initiative (OCI) artifacts, readily installable via Helm 3. Here's an abbreviated guide to help you hit the ground running:

Deploying a Boundary Controller

Before installation, ensure you have the necessary components ready: a PostgreSQL database, configured KMS keys, and the requisite Kubernetes secrets for the database connection, TLS certificates, and admin credentials.

kubectl create namespace boundary
helm install boundary-controller oci:///boundary-controller --namespace boundary --values values.yaml

The controller chart manages database initialization during the first installation. After setting up, confirm that the controller pods are operational:

kubectl get pods -n boundary

With admin bootstrapping enabled, authentication can be achieved using Kubernetes secrets right away.

Deploying a Boundary Worker

For worker deployment, prepare a worker HCL configuration file that specifies the required controller addresses, tags, and registration token (if opting for controller-led registration).

kubectl create namespace boundary
helm install boundary-worker oci:///boundary-worker --namespace boundary --set-file worker.config=/path/to/worker.hcl

Post-installation, check the worker pod’s status and logs to verify successful registration with the control plane:

kubectl get pods -n boundary
kubectl logs -n boundary deployment/boundary-worker

For instances with intermediate workers, note the load balancer's external address and update the worker configuration accordingly. Apply changes with a Helm upgrade:

helm upgrade boundary-worker oci:///boundary-worker --namespace boundary --reuse-values --set-file worker.config=/path/to/worker.hcl

Managing Upgrades

Both Helm charts support standard upgrade and rollback processes. For worker updates, modify the container image tag in your values and run a Helm upgrade, which restarts the worker pod while retaining persistent state. The termination grace period ensures that active sessions drain before stopping the pod.

For controller updates, changes in the configuration trigger automatic rolling updates. Database migrations require an explicit flag (--set controller.database.migrate.enabled=true) and should be preempted by a full backup, as migrations in Boundary cannot be reversed.

These new Helm charts align Boundary deployments more closely with existing Kubernetes management methods. They not only cater to self-managed customers by providing a production-obedient pathway for the full Boundary stack, but they also enable HCP Boundary customers to integrate their data planes within private networks efficiently.

Now available for use, the charts can be found on GitHub: explore the worker chart and controller chart repositories for further documentation, value references, and deployment guides. New users should refer to the self-managed deployment documentation and HCP Boundary getting started guide for foundational knowledge before proceeding with their Helm installations.

For additional insights into Boundary or to get started with HCP Boundary, visit hashicorp.com/boundary.