Install CloudGrange — Appliance mode

Appliance mode imports a prepared Ubuntu 24.04 VHDX that already contains K3s, the CloudGrange Helm release and every container image it needs. It is the fastest way to a running control plane and pulls nothing from the internet during import.

On first boot the appliance re-keys itself: a new hostname and machine identity, new SSH host keys, and freshly generated platform secrets. Nothing is shared between two appliances imported from the same VHDX.

The appliance always runs in offline mode: it carries an in-cluster registry, and K3s is configured to look there for images first. Platform, module and Foundation updates can all be uploaded as offline bundles, and online updates still work when the appliance can reach the internet. See Updates.

Compare installation modes

Prerequisites

Full details, including the virtual switch, the IP plan and the ports, are on Appliance prerequisites.

• A Windows host with Hyper-V and PowerShell 7, running as Administrator
• An existing Hyper-V virtual switch, or permission for the script to create the default internal switch
• About 40 GB free for the extracted VHDX and its growth (the download is roughly 3 GB, the disk about 6 GB)
• Inbound TCP 443 for the portal and API, and 8443 for managed agents
• A connected machine to download the two files if the Hyper-V host itself is offline

Download

The appliance is published on the CloudGrange download site, because it is larger than GitHub's release-asset limit. Download the zip and its .sha256 from appliance/<version>/, and the installer, which contains the import script:

$version = '2609.0.0-preview.26'
$base    = "https://pub-ab113af532ff44ef827c176e42118f17.r2.dev/appliance/$version"
Invoke-WebRequest "$base/cloudgrange-appliance-$version.zip"        -OutFile ".\cloudgrange-appliance-$version.zip"
Invoke-WebRequest "$base/cloudgrange-appliance-$version.zip.sha256" -OutFile ".\cloudgrange-appliance-$version.zip.sha256"

# Check the download before you expand it.
$expected = (Get-Content ".\cloudgrange-appliance-$version.zip.sha256" -Raw).Split()[0]
if ((Get-FileHash ".\cloudgrange-appliance-$version.zip" -Algorithm SHA256).Hash -ine $expected) {
  throw 'Appliance SHA-256 mismatch: download it again'
}
Expand-Archive ".\cloudgrange-appliance-$version.zip" -DestinationPath '.\cloudgrange-appliance'

# The installer carries Import-CloudGrangeAppliance.ps1.
Invoke-WebRequest 'https://github.com/CloudGrange/cloudgrange-deployment-installer/releases/latest/download/Install-CloudGrange-Windows.zip' -OutFile '.\Install-CloudGrange-Windows.zip'
Expand-Archive '.\Install-CloudGrange-Windows.zip' -DestinationPath '.\cloudgrange-installer'

The zip contains cloudgrange-appliance-k3s.vhdx, its .sha256, and cloudgrange-appliance.version.

Import

CloudGrange publishes no signing key: an appliance is trusted through HTTPS and the SHA-256 published beside it. Import-CloudGrangeAppliance.ps1 verifies the VHDX against that checksum and refuses to create a VM if it does not match.

In PowerShell 7 as Administrator:

Set-Location '.\cloudgrange-installer'
.\Import-CloudGrangeAppliance.ps1 `
  -AppliancePath '..\cloudgrange-appliance\cloudgrange-appliance-k3s.vhdx' `
  -VmName 'cloudgrange'

Leave out -SwitchName and the script uses a switch named cloudgrange-external, creating it as an External switch on the host's default-route adapter if it does not exist (the host's own network drops for a few seconds while Hyper-V creates it). The appliance then takes a DHCP address from that network. On a network without DHCP, or to place the appliance on a switch you already have, pass -SwitchName with a static plan:

.\Import-CloudGrangeAppliance.ps1 `
  -AppliancePath '..\cloudgrange-appliance\cloudgrange-appliance-k3s.vhdx' `
  -VmName 'cloudgrange' -SwitchName '<existing-switch>' `
  -VmIp 192.168.100.12 -PrefixLength 24 -Gateway 192.168.100.1 -DnsServers 8.8.8.8

The script creates a Generation 2 VM with Secure Boot and Hyper-V KVP enabled, starts it, waits for first boot to finish, and then prints the portal URL and the appliance's credentials. It also saves an operator SSH key under %USERPROFILE%\.ssh. First boot takes a few minutes: the appliance re-keys itself and installs the Helm release from the images already on the disk.

Record the credentials when they are shown and complete setup promptly. They are withdrawn from KVP and from the console banner once setup is complete.

First run

Open the portal URL the script printed. The setup wizard runs on the first visit: it creates your administrator account and names the platform. The portal uses a certificate issued by the appliance's own CA, so your browser warns until you trust that CA or install your own certificate. Platform → CLI offers the CA file and the cg download.

Verify

Over SSH with the operator key, or from the VM console:

sudo k3s kubectl get pods -A
sudo k3s kubectl get nodes
sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml helm status cloudgrange

Every pod should be Running or Completed, and get nodes should list exactly one node: this appliance.

After the control plane is running

• Install the CloudGrange Agent on every Hyper-V host you want to manage. The appliance is its own site relay, so there is nothing else to install for that.
• Apply updates from Platform → Updates, online or as uploaded offline bundles.

See current product and release status.