Skip to content

Prerequisites

Status: Alpha Last Updated: 2026-06-06

This document is the prerequisites checklist for installing vworkspace-operator. Most items are properties of the cluster you already run; a few have opinionated recommendations for the cases that warrant them.

Kubernetes version

Component Minimum supported Recommended Tested by the project
Kubernetes API server 1.28 1.30 or newer 1.28, 1.30, 1.31
kubectl (admin's machine) 1.28 Same major/minor as the cluster n/a

The minimum is set by the CRDs (apiVersion: apiextensions.k8s.io/v1 with status subresources and structural schemas) and the snapshot APIs the operator integrates with. Older clusters may work but are not tested.

Distro-specific notes (k3s, Talos, Harvester, EKS/GKE/AKS, single-node Docker host with embedded k3s) are in kubernetes-distros.md.

CNI

Any standard CNI plugin is supported. The operator does not care which one is installed; it does not configure NetworkPolicies on its own (planned: see ../security/threat-model.md open issues), it does not depend on any vendor-specific feature, and it does not depend on a service-mesh sidecar.

If you plan to enforce NetworkPolicies (recommended for production), the CNI must support networking.k8s.io/v1 NetworkPolicy. Common choices that do: Cilium, Calico, Canal, Antrea, and the CNI shipped with EKS/GKE/AKS.

Storage

The operator does not require any specific storage backend. Two recommendations for production:

  • A default StorageClass. Most charts in the vWorkspace catalog request a PVC without specifying a storageClassName, and rely on the cluster's default. At least one StorageClass should have the storageclass.kubernetes.io/is-default-class: "true" annotation.
  • A VolumeSnapshotClass whose driver supports snapshots. Velero's CSI path and the operator's snapshot engine both rely on the CSI snapshot controller and a VolumeSnapshotClass mapped to the storage driver. Without this, backups fall back to file-system backup (Velero's Restic/Kopia path), which is supported but slower and less consistent.

For single-node clusters with no cloud storage, local-path (from Rancher's local-path-provisioner) is a fine default StorageClass; snapshot support requires a snapshot-capable driver such as TopoLVM or Longhorn. The bundle works without snapshots (Velero falls back to Restic/Kopia for file-system backup), but the storage-only engine in ../operations/engines/csi-snapshots-volsync.md is unavailable until snapshots are wired up.

Controllers installed by the operator's bundle

Default chart values install only the vworkspace-operator Deployment, CRDs, and RBAC. Flux, Velero, cert-manager, and external-secrets are not installed unless you enable bundle flags — see helm.md.

Bundle v1 (Session 3 dogfood; values-kind.yaml or explicit --set):

Controller Chart flag v1 status Override when already present
Flux helm-controller + source-controller flux.enabled=true Bundled (pinned flux2 v2.4.0 subset) flux.installed=false
Velero + in-cluster MinIO (kind lab) velero.enabled=true, velero.minio.enabled=true Bundled (Velero v1.15.0 + MinIO) velero.installed=false
cert-manager certManager.enabled Not bundled v1 Bring your own
external-secrets externalSecrets.enabled Not bundled v1 Bring your own

Argo Workflows is not installed by the chart. Operation templates that require Argo Workflows will be admitted but block (Blocked=True/EngineNotInstalled) until it is present.

For production clusters that already run cluster-wide Flux or Velero, set *.installed=false and point the operator at your existing install rather than duplicating controllers.

Ingress controller

You provide the ingress controller of your choice (Nginx Ingress Controller, Traefik, HAProxy Ingress, Contour, or the cloud provider's ingress). The chart does not install one. Application charts that need an ingress create the Ingress object; your controller routes to it.

Two notes:

  • cert-manager is not in bundle v1. Charts that request TLS certificates need cert-manager installed separately, or use inline/dev secrets on kind.
  • For air-gapped or single-node installs, k3s ships Traefik by default; if you run with --disable=traefik and bring Nginx, take note in kubernetes-distros.md.

Egress

The operator's Pull-mode default needs outbound HTTPS (port 443) to the vWorkspace Server control plane. No inbound port on the cluster is required for Pull. Concretely:

  • The operator pod's outbound HTTP client must reach https://<control-plane-host> for /api/agent/* endpoints. The host is set in Cluster.spec.controlPlaneEndpoint (or the deprecated controlPlaneBaseUrl alias) when you apply the bootstrap Cluster CR — not via Helm values.
  • Velero needs outbound access to the configured BackupStorageLocation (S3, GCS, Azure Blob, MinIO, on-prem object store). Configure your egress firewall accordingly.
  • external-secrets needs outbound access to whichever upstream secret store you use (Vault, AWS, GCP, Azure, Akeyless, etc.).
  • cert-manager needs outbound access to your ACME endpoint (typically Let's Encrypt).
  • The Helm engine needs outbound access to your chart sources (an OCI registry, a Helm repository).

Push and GitOps modes change the cluster-side egress profile: Push needs Odoo to reach the cluster API (an inbound credential on the cluster's side); GitOps needs the cluster to reach Git. See ../security/authentication.md for the credential model in each mode.

RBAC to install

Installing the bundle requires cluster-admin privileges on the target cluster (or an equivalent role that can install CRDs, ClusterRoles, ClusterRoleBindings, and webhooks). This is true for the install only; the operator does not run with cluster-admin after install — see ../security/rbac.md and ../security/least-privilege.md.

In practice, helm install runs as a user with cluster-admin (your kubeconfig admin context); the operator's runtime principal is the ServiceAccount the chart creates, which has only the rights described in the RBAC reference.

Time

Time sync (NTP or equivalent) must be working on every node and on the admin's machine. The one-time registration token has a short TTL; signed payloads in Pull mode rely on timestamps; certificate issuance via cert-manager assumes clock skew within a few minutes. Most managed Kubernetes deployments handle this automatically; bare-metal clusters should run chronyd or systemd-timesyncd.

Resource footprint

The bundle adds the following pods to the cluster (approximate steady-state, exclusive of applications):

Pod Replicas CPU request Memory request Notes
vworkspace-operator 1 10m 64Mi Leader-elected manager.
helm-controller (optional bundle) 1 100m 64Mi Flux — when flux.enabled=true.
source-controller (optional) 1 50m 64Mi Flux — when flux.enabled=true.
velero (optional bundle) 1 100m 128Mi When velero.enabled=true.
minio (optional, kind lab) 1 — — When velero.minio.enabled=true.

A 2 vCPU / 4 GiB RAM single-node cluster is sufficient to install the operator and the bundle's controllers. Application workloads are on top of this footprint.

What to have ready before starting

A short checklist before you run the first helm install:

  • A kubeconfig pointing at the target cluster with cluster-admin rights (or equivalent for installing CRDs and webhooks).
  • The cluster's default StorageClass identified (kubectl get sc). If none is default, decide whether to set one before install.
  • A reachable control plane URL (Pull mode) and the ability to log in as an organization admin to issue a registration token.
  • The cluster's egress destinations approved in your firewall (control plane URL, chart source registry, BackupStorageLocation, external secret store, ACME endpoint).
  • For air-gapped installs: a private OCI registry mirror and a private Helm chart mirror, plus the procedure described in offline-and-airgapped.md.

Once you have these, quickstart.md is two commands.