Install CloudGrange — Online mode (Windows-orchestrated)

Online mode runs on a Windows host with Hyper-V. It creates an Ubuntu 24.04 VM, installs K3s inside that guest, and deploys the CloudGrange Helm chart onto it. You end up with a Kubernetes cluster running CloudGrange on a VM the installer built for you. Use it when the guest can reach the internet.

CloudGrange is in preview, not GA. The commands on this page always download the latest release. See current product and release status.

Compare installation modes

Mode Control-plane host Engine Initial network requirement
Online Windows + Hyper-V; installer creates a Linux VM K3s + Helm Internet access from the guest
Bundled Windows + Hyper-V; installer creates a Linux VM K3s + Helm (offline images) Offline after transferring the files
Appliance Windows + Hyper-V; import a prepared Linux VHDX K3s + Helm Offline import
Native Linux Existing Linux server; no Windows/Hyper-V K3s + Helm None after downloading the bundle (it carries every image)
Helm A Kubernetes cluster you already run Helm only Internet access for image pulls

Prerequisites

Full details, including the VM the script creates and its network, are on Windows script prerequisites.

  • Windows Server with the Hyper-V role, or Windows 10/11 with the Hyper-V feature
  • Administrator rights on the host
  • PowerShell 7 and the Windows OpenSSH client
  • qemu-img on PATH, or explicit use of -InstallPinnedQemu
  • At least 64 GB free at the VHDX path
  • Outbound HTTPS from the guest to Ubuntu download sources, get.k3s.io, get.helm.sh and ghcr.io
  • Inbound TCP 443 for the portal/API. The script forwards the host's port 443 to the VM. It does not forward 8443, so managed hosts on other machines need a route to the VM (for example, an External switch)

Download and verify

Open PowerShell 7 as Administrator:

$base = 'https://github.com/CloudGrange/cloudgrange-deployment-installer/releases/latest/download'
$zip = 'Install-CloudGrange-Windows.zip'
Set-Location $HOME

Invoke-WebRequest "$base/$zip" -OutFile $zip
Invoke-WebRequest "$base/$zip.sha256" -OutFile "$zip.sha256"

$expected = (Get-Content "$zip.sha256" -Raw).Split()[0]
$actual = (Get-FileHash $zip -Algorithm SHA256).Hash
if ($actual -ine $expected) { throw 'Installer SHA-256 mismatch: delete both files and download them again' }

Expand-Archive $zip -DestinationPath '.\cloudgrange-installer' -Force
Set-Location '.\cloudgrange-installer'
Get-Content .\VERSION

The download is trusted the same way CloudGrange trusts its updates: it comes over HTTPS from the CloudGrange GitHub release, and its SHA-256 must match the published checksum. Install-CloudGrange.ps1 also checks its own SHA-256 against cloudgrange-installer.sha256 before it changes anything. VERSION shows which release you downloaded.

Install

.\Install-CloudGrange.ps1 -Mode Online -AcceptDefaults

The installer deploys the release you downloaded; the chart inside the package is stamped with that version. -Engine defaults to K3s.

Useful overrides:

Parameter Default Purpose
-VmIp 192.168.100.10 Guest IP address
-VhdxPath C:\ProgramData\CloudGrange\cloudgrange-k3s.vhdx VM disk location
-SwitchName (first external switch) Hyper-V virtual switch
-InstallPinnedQemu off Download and SHA-512-verify the pinned QEMU build
-Engine Compose K3s Deploy the legacy Compose stack instead

Each engine gets its own VM name and disk — cloudgrange-k3s / cloudgrange-k3s.vhdx for K3s, cloudgrange-docker / cloudgrange-docker.vhdx for Compose — so installing one never disturbs an existing VM built by the other. An explicit -VhdxPath is always honoured as given.

What the installer does

  1. Provisions the Ubuntu 24.04 VM in Hyper-V and waits for SSH.
  2. Installs K3s in the guest and waits for the node to report Ready.
  3. Installs cert-manager as its own Helm release.
  4. Runs helm upgrade --install cloudgrange with the single-node values.
  5. Fails the install if any pod is not Ready or the Ingress is missing.

Complete setup

When health checks pass, the installer prints the portal URL, the one-use setup token (when required), and the temporary administrator password. Record them, browse to the printed HTTPS URL, accept the temporary self-signed certificate warning, complete setup, and change the temporary password.

Verify from the Windows host

ssh cloudgrange@192.168.100.10 'sudo k3s kubectl get pods'
ssh cloudgrange@192.168.100.10 'sudo k3s kubectl get ingress'

Every pod should be 1/1 Running, except cloudgrange-secrets-bootstrap-*, a one-shot Job that correctly ends 0/1 Completed.

Offline installs

For a Kubernetes install with no internet access from the guest, use Bundled mode: the same installer, with K3s, Helm and every image taken from the Linux release bundle's airgap/ directory.

After the control plane is running

See current product and release status.