Install CloudGrange — Bundled mode
Bundled mode runs on a Windows host with Hyper-V and creates an Ubuntu 24.04 VM, like Online mode, but the VM needs no internet access: K3s, Helm and every container image come from the Linux release bundle's airgap/ directory, and the Ubuntu image comes from a file you download in advance.
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 | Initial network requirement |
|---|---|---|
| Online | Windows + Hyper-V; installer creates a Linux VM | Internet access from the guest |
| Bundled | Windows + Hyper-V; installer creates a Linux VM | Offline after transferring the files |
| Appliance | Windows + Hyper-V; import a prepared Linux VHDX | Offline import |
| Native Linux | Existing Linux server; no Windows/Hyper-V | None after downloading the bundle |
Prerequisites
- A connected machine on which to download the files
- Windows Server 2022/2025 or Windows 10/11 with Hyper-V enabled on the target
- PowerShell 7 and the Windows OpenSSH client
- At least 64 GB free at the VHDX path
- Inbound TCP 443 for the portal/API and 8443 for managed agents
The release pins a ready-made Ubuntu 24.04 Hyper-V disk, so no disk-conversion tools (QEMU) are needed. The installer checks the disk against the SHA-256 the release pins before it uses it.
Download and verify
On a connected machine, open PowerShell 7:
$base = 'https://github.com/CloudGrange/cloudgrange-deployment-installer/releases/latest/download'
Set-Location $HOME
foreach ($zip in 'Install-CloudGrange-Windows.zip', 'Install-CloudGrange-K3s-Bundled.zip') {
Invoke-WebRequest "$base/$zip" -OutFile $zip
Invoke-WebRequest "$base/$zip.sha256" -OutFile "$zip.sha256"
$expected = (Get-Content "$zip.sha256" -Raw).Split()[0]
if ((Get-FileHash $zip -Algorithm SHA256).Hash -ine $expected) { throw "$zip SHA-256 mismatch: download it again" }
}
Expand-Archive 'Install-CloudGrange-Windows.zip' -DestinationPath '.\cloudgrange-installer' -Force
Expand-Archive 'Install-CloudGrange-K3s-Bundled.zip' -DestinationPath '.\cloudgrange-bundle' -Force
# The ready-made Ubuntu 24.04 Hyper-V disk this release pins, checked against the pinned SHA-256.
$pins = Get-Content '.\cloudgrange-installer\release\pins.conf'
$pin = { param($k) ($pins | Select-String "^$k=(.+)$").Matches[0].Groups[1].Value }
$vhdxZip = '.\ubuntu-base-vhdx.zip'
Invoke-WebRequest (& $pin 'UBUNTU_BASE_VHDX_ZIP_URL') -OutFile $vhdxZip
if ((Get-FileHash $vhdxZip -Algorithm SHA256).Hash -ine (& $pin 'UBUNTU_BASE_VHDX_ZIP_SHA256')) { throw 'Ubuntu base disk SHA-256 mismatch: download it again' }
Expand-Archive $vhdxZip -DestinationPath '.\cloudgrange-bundle' -Force
Transfer cloudgrange-installer and cloudgrange-bundle to the Windows host.
Install
Open PowerShell 7 as Administrator in the cloudgrange-installer directory:
.\Install-CloudGrange.ps1 -Mode Bundled `
-BundlePath (Resolve-Path '..\cloudgrange-bundle').Path `
-AcceptDefaults
For a guest with no default route, add -NoDefaultGateway. Use -VmIp, -VhdxPath, or -SwitchName to override defaults.
When health checks pass, record the portal URL and one-use credentials printed once by the installer, then complete setup in the browser and change the temporary identity-admin password.