Tutorial

Deploy on Kubernetes (Helm)

This is the Kubernetes path to the same end state as the Compose getting-started: a healthy, ready Workbench. You install the official Helm chart, back it with the master-key secret and two persistent volumes, and confirm /healthz — then pick up admin creation and license activation from the how-to guides. It assumes a working cluster, kubectl, and Helm v3.

What the chart provisions

A StatefulSet running exactly one pod (the chart pins replicaCount: 1 and the Recreate strategy — one process per license).
Two volumeClaimTemplate PVCs: identity (/var/lib/arq) and data (/var/lib/arq-workbench), both ReadWriteOnce. They are retained on helm uninstall.
One ClusterIP Service on port 8080.

The chart deliberately ships no Ingress and no HPA — expose and scale-to-fit are environment-specific, so you bring your own Ingress/Gateway and TLS in front of the Service.

Prerequisites

Kubernetes 1.27+, kubectl, and Helm v3.
A default StorageClass that supports ReadWriteOnce.
cosign v2.x to verify the chart (recommended).
A license file from Elevarq — needed at activation, not at install.

1. Get and verify the chart

The chart is published as a Cosign-signed .tgz asset on each release. Download it (and its signature bundle), then verify before installing:

TAG=v0.1.0
CHART=arq-workbench-0.1.0.tgz   # chart version tracks the release tag

# (download CHART and CHART.cosign.bundle from the release, then:)
cosign verify-blob "$CHART" \
  --bundle "$CHART.cosign.bundle" \
  --certificate-identity-regexp '^https://github.com/Elevarq/.+/\.github/workflows/release\.yml@.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

2. Create the master-key secret

The master key is required — Workbench refuses to boot without it, and it is the root of at-rest encryption for every stored credential. Create it as a Secret the chart references (rather than inlining it into values):

kubectl create namespace arq

kubectl create secret generic workbench-master-key \
  --namespace arq \
  --from-literal=master-key="$(openssl rand -hex 32)"

Back this value up outside the cluster, in your secret manager. An intact data volume with a lost master key is unrecoverable — see the safety model.

3. Install the chart

helm install arq-workbench ./arq-workbench-0.1.0.tgz \
  --namespace arq \
  --set masterKey.existingSecret=workbench-master-key \
  --set image.tag=0.1.0

The chart's NOTES.txt prints the port-forward line. For production, pin an immutable digest (image.tag: "0.1.0@sha256:<digest>") and set PVC sizes / storageClass to match your cluster.

masterKey.existingSecretKey defaults to master-key, matching the secret created in step 2. Setting persistence.*.accessMode=ReadWriteMany or replicaCount>1 is rejected/warned — Workbench runs as one process per license.

4. Verify it's healthy

kubectl --namespace arq get pods
kubectl --namespace arq port-forward svc/arq-workbench 8080:8080 &
curl -fsS http://127.0.0.1:8080/healthz
# {"status":"ok","version":"v0.1.0", ... ,"licensing":{"cache_state":"empty"}}

cache_state: "empty" is correct until you activate a license.

Where next

From a healthy pod the flow is identical to any other deployment:

Create the first admin and activate your license (air-gapped clusters use offline activation).
Put an Ingress/Gateway with TLS in front of the ClusterIP Service before exposing it.
Plan backups of both PVCs (CSI volume snapshots or Velero) — especially the identity volume — alongside the off-cluster master key.