Skip to content

Helm install guide

Status: Alpha Last Updated: 2026-06-06

This document is the full reference for installing vworkspace-operator with the in-repo Helm chart at charts/vworkspace-operator/. For the shortest path, start with quickstart.md Option A.

Default values install the operator controller, CRDs, and RBAC only. Optional bundle v1 flags (flux.enabled, velero.enabled) add Flux controllers and Velero + MinIO for Session 3 dogfooding — see Bundle v1 (Session 3) and values-kind.yaml.

Prerequisites

  • Kubernetes 1.28 or newer with cluster-admin access via kubectl.
  • Helm 3.13 or newer.
  • A container registry pull path for vworkspace/vworkspace-operator (Docker Hub by default) or a locally built image.
  • Optional: kind for local validation (hack/validate-helm-kind.sh).

Install from repository checkout

helm install vworkspace-operator ./charts/vworkspace-operator \
  -n vworkspace-system \
  --create-namespace \
  --set image.tag=latest

Install from GitHub Release

Published on every v* git tag (release process). Replace 0.0.7 with the version you are installing (releases page).

Helm (operator + CRDs + RBAC; default bundle flags off):

helm upgrade --install vworkspace-operator \
  https://github.com/vworkspace-io/vworkspace-operator/releases/download/v0.0.7/vworkspace-operator-0.0.7.tgz \
  --version 0.0.7 \
  -n vworkspace-system \
  --create-namespace

The chart pins image.tag to the git tag (v0.0.7) because container images use the v-prefixed tag on Docker Hub while chart appVersion is bare SemVer.

kubectl (no Helm; operator-only profile — apply CRDs first):

kubectl apply -f https://github.com/vworkspace-io/vworkspace-operator/releases/download/v0.0.7/crds.yaml
kubectl apply -f https://github.com/vworkspace-io/vworkspace-operator/releases/download/v0.0.7/operator.yaml
kubectl -n vworkspace-system wait --for=condition=Available \
  deployment/vworkspace-operator --timeout=300s

Verify checksums: download SHA256SUMS from the same release assets.

Maintainers package locally: VERSION=0.0.7 make package-release (outputs under dist/release/).

The release name (vworkspace-operator) and namespace (vworkspace-system) are conventions. The chart works with any release name; if you change the namespace, set Cluster.spec and registration commands to match.

Tested values (kind validation)

These values are exercised by ./hack/validate-helm-kind.sh:

Key Value Notes
image.repository vworkspace/vworkspace-operator Chart default
image.tag latest or locally built helm-validate Use latest when pulling from Docker Hub
crds.install true Installs ApplicationInstance, Operation, Cluster CRDs
agent.pollIntervalSeconds 30 (default) or 5 in values-kind.yaml Operator-wide long-poll interval
agent.credentialsSecret vworkspace-agent-credentials Default name; written by Cluster reconciler

Pull-mode connectivity is not configured at install time. After helm install, apply a token Secret and Cluster CR (cluster-bootstrap.md). Example templates: charts/vworkspace-operator/examples/cluster-bootstrap/.

Values reference

Key Default Description
image.repository vworkspace/vworkspace-operator Operator container image
image.tag Chart appVersion Image tag (latest for CI-published builds on main)
image.pullPolicy IfNotPresent Kubernetes pull policy
replicaCount 1 Manager Deployment replicas
crds.install true Render CRDs from files/crds/ via chart template
agent.credentialsSecret vworkspace-agent-credentials Default credentials Secret name (overridden by Cluster.status.credentialsSecretRef)
agent.pollIntervalSeconds 30 Operator-wide Pull-mode long-poll interval
rbac.create true ClusterRole and ClusterRoleBinding
serviceAccount.create true Dedicated ServiceAccount
manager.metricsBindAddress 0 (off) Set to :8443 to expose HTTPS /metrics (see observability.md)

See charts/vworkspace-operator/values.yaml for manager flags, resources, scheduling, and bundle keys (flux, velero).

Bundle v1 (Session 3)

Hub design: session-3-helm-path-design.md.

Key Default Description
flux.enabled false Install helm-controller + source-controller into flux-system
flux.installed true Set false when Flux already exists (skip chart install)
velero.enabled false Install Velero server + CRDs
velero.minio.enabled false In-cluster MinIO + BSL for kind (matches server BACKUP_E2E.md)
velero.installed true Set false when Velero already exists
certManager.enabled false Placeholder — not bundled in v1
externalSecrets.enabled false Placeholder — not bundled in v1

Kind / dogfood profile — single install with metrics, Flux, Velero, and MinIO (no connectivity Helm values):

helm upgrade --install vworkspace-operator ./charts/vworkspace-operator \
  -n vworkspace-system --create-namespace \
  -f charts/vworkspace-operator/values-kind.yaml

Then apply cluster bootstrap manifests (examples/cluster-bootstrap/). Pin the operator image at run time: --set image.tag=<sha-tag>.

CRD installation

CRDs ship under charts/vworkspace-operator/files/crds/ (not Helm's reserved crds/ folder) and are applied when crds.install=true through templates/crds.yaml. Using files/crds/ avoids Helm installing CRDs twice — once without release ownership and again via the template — which fails with invalid ownership metadata on fresh clusters.

To manage CRDs outside Helm (GitOps or cluster bootstrap), set crds.install=false and apply CRDs separately:

kubectl apply -f charts/vworkspace-operator/files/crds/

Post-install: connect to the control plane

After helm install, the operator is running but not yet connected to vWorkspace Server. Connectivity is declarative — no second helm upgrade, no agent.enabled toggle.

  1. Issue a registration token in vWorkspace Server (Cluster Registry). See cluster-bootstrap.md Step 3.

  2. Apply bootstrap manifests — token Secret + Cluster CR referencing that Secret:

# Edit placeholders first, then apply from repo root:
kubectl apply -f charts/vworkspace-operator/examples/cluster-bootstrap/registration-token.secret.yaml
kubectl apply -f charts/vworkspace-operator/examples/cluster-bootstrap/cluster.yaml
kubectl get cluster cluster-local -w

The reconciler exchanges the token, writes Secret/vworkspace-agent-credentials, and the Pull-mode agent starts automatically when credentials exist.

  1. Validate — Cluster.status.phase=Connected and Connected=True; see quickstart.md Step 3.

Helm prints the same hints in the release notes (NOTES.txt). Break-glass kubectl exec … /manager register is documented in cluster-bootstrap.md#break-glass-register-cli.

Upgrade and uninstall

Upgrade after changing values or image tag:

helm upgrade vworkspace-operator ./charts/vworkspace-operator \
  -n vworkspace-system \
  --reuse-values \
  --set image.tag=<new-tag>

Uninstall the release (uninstall.md):

helm uninstall vworkspace-operator -n vworkspace-system

CRDs installed by the chart are not removed automatically. Delete them explicitly if decommissioning the cluster:

kubectl delete -f charts/vworkspace-operator/files/crds/ --ignore-not-found

Local validation on kind

Run the automated check (creates a kind cluster, installs the chart, waits for Ready, optional Flux CRDs):

chmod +x hack/validate-helm-kind.sh
./hack/validate-helm-kind.sh

Environment variables:

Variable Default Purpose
KIND_CLUSTER vworkspace-operator-helm-validate kind cluster name
USE_PUBLISHED_IMAGE 0 Set to 1 to pull latest from Docker Hub instead of building locally
VALIDATE_BUNDLE false Set to true to install with values-kind.yaml (Flux + Velero + MinIO + metrics)
INSTALL_FLUX_CRDS false Apply Flux CRDs only (contract tier — no controller pods). Ignored when VALIDATE_BUNDLE=true.
DELETE_CLUSTER true Delete kind cluster when the script created it

Or via Makefile:

make validate-helm-kind

Contract tier (CRDs only, matches e2e and Phase 1 golden path):

INSTALL_FLUX_CRDS=true ./hack/validate-helm-kind.sh

Session 3 bundle tier (Flux controllers + Velero + MinIO; pulls published operator image):

VALIDATE_BUNDLE=true ./hack/validate-helm-kind.sh

Optional Flux controllers for Ready

INSTALL_FLUX_CRDS=true installs the API types the operator needs to create HelmRelease resources. It does not install helm-controller or source-controller. Without those Deployments, HelmRelease objects are not reconciled and ApplicationInstance will not reach Ready — see cluster-bootstrap.md#flux-contract-only-vs-full-reconcile.

To reach full reconcile on kind after the in-repo chart and CRDs:

# Flux CLI — installs controllers into flux-system
flux check --pre
flux install

Or install Flux via the Helm bundle:

helm upgrade --install vworkspace-operator ./charts/vworkspace-operator \
  -n vworkspace-system --reuse-values \
  --set flux.enabled=true

Or use values-kind.yaml for the full Session 3 profile (Bundle v1).

Verify controllers:

kubectl get deploy -n flux-system helm-controller source-controller
kubectl get helmreleases -A

Render without applying

helm template vworkspace-operator ./charts/vworkspace-operator \
  --namespace vworkspace-system \
  -f charts/vworkspace-operator/values-kind.yaml