boundary helm documentation

docs/documentation/1-overview.md

@@ -0,0 +1,71 @@
+# Boundary Helm charts
+
+Important Note: These charts are not compatible with Helm 2. Use Helm 3.x.
+
+Boundary can run on Kubernetes with separate Helm charts for the two Boundary runtime roles:
+
+- The Boundary controller chart installs the Boundary control-plane components.
+- The Boundary worker chart installs self-managed Boundary data-plane workers.
+
+The charts are separate because controllers and workers have different lifecycle, scaling, persistence, and exposure requirements.
+
+## 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 controller-backed Boundary deployment needs a PostgreSQL database and KMS configuration. A worker deployment needs valid worker HCL, a registration model, and persistent storage when the selected worker authentication or recording configuration requires it.
+
+## Chart responsibilities
+
+The charts package Kubernetes resources and Helm release workflows. They do not replace 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 | Worker identity and optional session recordings can be persisted with PVCs. |
+
+## Controller chart summary
+
+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, optional database migration, optional database repair, and optional admin bootstrap.
+
+The controller chart expects you to provide required external dependencies such as PostgreSQL, KMS access, Boundary Enterprise license data, and TLS material when TLS is enabled.
+
+Controller installation documentation is intentionally separate from worker installation documentation.
+
+## Worker chart summary
+
+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 uses the official `hashicorp/boundary-enterprise` image by default. It mounts user-provided worker HCL from `worker.config`, exposes optional proxy and operations Services, and provisions optional PVCs for auth storage and session recording storage.
+
+## Shared configuration model
+
+Both charts separate configuration into two layers:
+
+1. Boundary runtime configuration supplied as HCL through a chart value.
+2. Kubernetes infrastructure configuration supplied through Helm values.
+
+The charts do not infer all runtime settings from Kubernetes values. You must keep listener ports, addresses, storage paths, TLS settings, and registration settings aligned between Boundary HCL and the Kubernetes resources created by the chart.
+
+## Documentation organization
+
+The documentation is organized by chart role:
+
+1. This overview contains information that applies to both Boundary Helm charts.
+2. [Controller chart documentation](2-controller/1-install.md) contains the current controller chart installation, configuration, and examples.
+3. [Worker chart documentation](3-worker/1-install.md) contains the current worker chart installation, configuration, and examples.
+
+Use the controller section for the current controller chart documentation:
+
+- [Install a Boundary controller](2-controller/1-install.md)
+- [Configure the controller chart](2-controller/2-configuration.md)
+- [Controller examples](2-controller/3-examples.md)
+
+Use the worker section for the current worker chart documentation:
+
+- [Install a Boundary worker](3-worker/1-install.md)
+- [Configure the worker chart](3-worker/2-configuration.md)
+- [Worker examples](3-worker/3-examples.md)

docs/documentation/2-controller/1-install.md

@@ -0,0 +1,273 @@
+# Boundary controller Helm chart installation
+
+## Prerequisites
+
+Before installing the chart, make sure the following are available:
+
+- A Kubernetes cluster supported by the chart.
+- Helm 3.x configured with access to the target Kubernetes cluster.
+- A reachable PostgreSQL database for Boundary controller state.
+- A valid Boundary controller HCL configuration.
+- KMS configuration for the `root`, `recovery`, and `worker-auth` purposes.
+- An existing Kubernetes Secret containing the database URL and Boundary Enterprise license.
+- An existing Kubernetes Secret containing `admin-username` and `admin-password` when `bootstrapAdmin.enabled=true`.
+- A Kubernetes TLS Secret containing `tls.crt` and `tls.key` when `tls.disabled=false`.
+- A ServiceAccount that the controller Deployment and hook Jobs can use.
+
+The controller chart deploys a stateless Boundary control plane. Persistent controller state is stored in PostgreSQL, not on the controller pods.
+
+## Add the HashiCorp Helm repository
+
+Add the Helm repository and confirm the chart is visible:
+
+```shell
+helm repo add hashicorp https://helm.releases.hashicorp.com
+helm repo update
+helm search repo hashicorp/boundary-controller
+```
+
+Example output:
+
+```text
+NAME                          CHART VERSION   APP VERSION   DESCRIPTION
+hashicorp/boundary-controller 0.1.0           0.21-ent      Boundary controller Helm chart
+```
+
+## Create the controller Secret
+
+The chart reads sensitive values from an existing Kubernetes Secret referenced by `secretRefs.secretName`. At minimum, create a Secret with the database URL and Boundary Enterprise license. Include bootstrap admin credentials when bootstrap admin creation is enabled.
+
+```shell
+kubectl create secret generic boundary-controller-secrets \
+  --namespace boundary \
+  --from-literal=database-url='postgres://boundary:password@postgres:5432/boundary?sslmode=require' \
+  --from-literal=license='<boundary-enterprise-license>' \
+  --from-literal=admin-username='admin' \
+  --from-literal=admin-password='<strong-password>'
+```
+
+If your `controller.config` uses `migration_url = "env://BOUNDARY_PG_MIGRATION_URL"`, also add the migration URL key expected by `secretRefs.keys.migrationUrl`.
+
+## Create the TLS Secret when TLS is enabled
+
+If `tls.disabled=false`, create the Kubernetes TLS Secret before installation:
+
+```shell
+kubectl create secret tls boundary-controller-tls \
+  --namespace boundary \
+  --cert=tls.crt \
+  --key=tls.key
+```
+
+When TLS is disabled, the chart does not mount this Secret.
+
+## Prepare the controller configuration
+
+The chart reads raw Boundary HCL from `controller.config`. Embed the HCL in a values file and pass it with `-f`.
+
+Start from the controller configuration guidance in [Configure controllers](https://developer.hashicorp.com/boundary/docs/configuration/controller) if you need a base controller configuration.
+
+At minimum, a usable controller configuration usually includes:
+
+- An API listener.
+- A cluster listener.
+- An operations listener.
+- A `controller` block with `license` and `database.url`.
+- `public_cluster_addr` so workers can reach the cluster listener.
+- KMS stanzas for `root`, `recovery`, and `worker-auth`.
+
+Example controller configuration using AWS KMS:
+
+```hcl
+disable_mlock = true
+
+listener "tcp" {
+  address = "0.0.0.0:9200"
+  purpose = "api"
+  tls_disable = true
+}
+
+listener "tcp" {
+  address = "0.0.0.0:9201"
+  purpose = "cluster"
+}
+
+listener "tcp" {
+  address = "0.0.0.0:9203"
+  purpose = "ops"
+  tls_disable = true
+}
+
+controller {
+  name = "boundary-controller"
+  description = "Boundary controller running in Kubernetes"
+  public_cluster_addr = "boundary-controller-cluster.boundary.svc.cluster.local:9201"
+  license = "env://BOUNDARY_LICENSE"
+
+  database {
+    url = "env://BOUNDARY_PG_URL"
+  }
+}
+
+kms "awskms" {
+  purpose    = "root"
+  region     = "us-east-1"
+  kms_key_id = "alias/boundary-root"
+}
+
+kms "awskms" {
+  purpose    = "recovery"
+  region     = "us-east-1"
+  kms_key_id = "alias/boundary-recovery"
+}
+
+kms "awskms" {
+  purpose    = "worker-auth"
+  region     = "us-east-1"
+  kms_key_id = "alias/boundary-worker-auth"
+}
+```
+
+Note: Keep `disable_mlock = true` with the chart's default security model. The containers run without the elevated privileges required for memory locking.
+
+## Create a namespace
+
+```shell
+kubectl create namespace boundary
+```
+
+## List available chart versions
+
+To see available published versions:
+
+```shell
+helm search repo hashicorp/boundary-controller -l
+```
+
+## Install a Boundary controller
+
+Create a values file that contains `controller.config` and the Kubernetes overrides you need:
+
+```yaml
+secretRefs:
+  secretName: boundary-controller-secrets
+
+serviceAccount:
+  name: default
+
+tls:
+  disabled: true
+
+controller:
+  config: |
+    disable_mlock = true
+
+    listener "tcp" {
+      address = "0.0.0.0:9200"
+      purpose = "api"
+      tls_disable = true
+    }
+
+    listener "tcp" {
+      address = "0.0.0.0:9201"
+      purpose = "cluster"
+    }
+
+    listener "tcp" {
+      address = "0.0.0.0:9203"
+      purpose = "ops"
+      tls_disable = true
+    }
+
+    controller {
+      name = "boundary-controller"
+      public_cluster_addr = "boundary-controller-cluster.boundary.svc.cluster.local:9201"
+      license = "env://BOUNDARY_LICENSE"
+
+      database {
+        url = "env://BOUNDARY_PG_URL"
+      }
+    }
+
+    kms "awskms" {
+      purpose    = "root"
+      region     = "us-east-1"
+      kms_key_id = "<KMS ROOT KEY ID>"
+    }
+
+    kms "awskms" {
+      purpose    = "recovery"
+      region     = "us-east-1"
+      kms_key_id = "<KMS RECOVERY KEY ID>"
+    }
+
+    kms "awskms" {
+      purpose    = "worker-auth"
+      region     = "us-east-1"
+      kms_key_id = "<KMS WORKER AUTH KEY ID>"
+    }
+
+  service:
+    api:
+      type: LoadBalancer
+    cluster:
+      type: LoadBalancer
+    ops:
+      type: ClusterIP
+```
+
+Install the release:
+
+```shell
+helm install boundary-controller hashicorp/boundary-controller \
+  --version 0.1.0 \
+  --namespace boundary \
+  --create-namespace \
+  -f my-values.yaml
+```
+
+## Verify the deployment
+
+Check the rendered resources after installation:
+
+```shell
+kubectl get deployment,pods,svc,jobs,pdb -n boundary
+kubectl logs -n boundary deployment/boundary-controller
+```
+
+Confirm that:
+
+- The database initialization Job completes successfully when `database.init.enabled=true`.
+- The bootstrap admin Job completes successfully when `bootstrapAdmin.enabled=true`.
+- The controller pods become Ready.
+- The API, cluster, and ops Services match your intended exposure model.
+- Boundary API requests succeed against the controller API listener.
+- Workers can reach `public_cluster_addr` and register successfully.
+
+## Upgrade with database migration
+
+When the Boundary version requires a database migration, run the upgrade in a controlled sequence:
+
+1. Scale controller replicas to zero.
+2. Take a PostgreSQL backup.
+3. Run the upgrade with `database.migrate.enabled=true`.
+
+Example:
+
+```shell
+helm upgrade boundary-controller hashicorp/boundary-controller \
+  --version 0.1.0 \
+  --namespace boundary \
+  -f my-values.yaml \
+  --set controller.replicas=0
+```
+
+```shell
+helm upgrade boundary-controller hashicorp/boundary-controller \
+  --version 0.1.0 \
+  --namespace boundary \
+  -f my-values.yaml \
+  --set database.migrate.enabled=true
+```
+
+If you need to run a repair migration, also set `database.repair.version` to the Boundary migration version you need to repair.