Prerequisites — Windows script (Hyper-V)

Install-CloudGrange.ps1 runs on a Windows Hyper-V host. It creates an Ubuntu virtual machine, installs K3s in it, and installs the CloudGrange Helm chart. It is for customers who run Windows and Hyper-V but do not want to build a Linux server themselves.

The Windows script is a managed foundation. CloudGrange owns the VM's Foundation: the Ubuntu operating system and its updates, K3s and the host services. CloudGrange delivers those updates through the admin-started Foundation card in Platform → Updates. You own the Hyper-V host. See Updates and Support boundary.

CloudGrange is in active development and is not GA. See current product and release status.

Windows host

Requirement	Detail
Windows edition	Windows Server with the Hyper-V role, or Windows 10/11 with the Microsoft-Hyper-V-All feature. The script checks both and stops with `CG-INST-ERR-001` if Hyper-V is missing
Hyper-V PowerShell module	Installed automatically if missing. The script runs the Hyper-V cmdlets through Windows PowerShell 5.1 (`powershell.exe`)
Nested virtualization	Only if the host is itself a VM: it must expose virtualization extensions (`Set-VMProcessor -ExposeVirtualizationExtensions $true` on the parent)
PowerShell	PowerShell 7, run as Administrator. The script declares `#Requires -Version 7.0` and `-RunAsAdministrator`
OpenSSH client	The Windows OpenSSH client (`ssh`, `scp` and `ssh-keygen` on `PATH`). The script uses a one-time SSH key to configure the VM
qemu-img	On `PATH`, used to convert the Ubuntu cloud image to VHDX. Or pass `-InstallPinnedQemu` to install the pinned, SHA-512-verified QEMU for Windows build `20260811` from `qemu.weilnetz.de`. Without either, the script stops with `CG-INST-ERR-004` and installs nothing
Free disk	At least 64 GB free at the VHDX path (default `C:\ProgramData\CloudGrange\`). The script checks this before it creates the VM (`CG-INST-ERR-003`)

The VM it creates

Setting	Value
Name	`cloudgrange-k3s`
Generation	2, Secure Boot on (`MicrosoftUEFICertificateAuthority` template)
vCPU	4
Memory	8 GB, static
Disk	30 GB virtual disk (dynamically expanding VHDX)
Operating system	Ubuntu 24.04 LTS (`noble`) cloud image, SHA-256-checked against Canonical's published checksums
Kubernetes	K3s `v1.36.4+k3s1`, with its built-in Traefik ingress, ServiceLB and local-path storage
Helm	v3.22.0, checksum-verified
cert-manager	v1.21.2, from the chart bundle
Start and stop	Starts automatically with the host (30-second delay) and shuts down with it

Network

Parameter	Default	Meaning
`-SwitchName`	`cloudgrange-internal`	The Hyper-V switch. If it exists, it is used unchanged. If not, an Internal switch is created
`-VmIp`	`192.168.100.10`	The VM's static address. The /24 around it is the VM network, and `.1` is the host's gateway address on the switch
`-NoDefaultGateway`	off	No default route in the VM. Only valid with the offline mode
`-HttpProxy`, `-ProxyUser`	none	An outbound proxy. `HTTPS_PROXY` or `HTTP_PROXY` in the environment are used if these are not set
`-SkipHostPortForward`	off	Don't publish the portal on the host

When it creates the switch, the script also creates a WinNAT network (CloudGrangeNAT) for the /24, so the VM can reach the internet. Windows allows only one NAT network per host. If the host already runs one (Docker Desktop, WSL or a lab NAT), pass an existing switch with -SwitchName, and a -VmIp in a subnet that network already routes.

Choose a -VmIp subnet that does not overlap your LAN. The script checks the existing switches for conflicts.

Inbound access. The script adds a Windows Firewall rule (CloudGrange-Portal-443) and a netsh port proxy that forwards the host's TCP 443 to the VM. Users browse to the host's address. Only 443 is forwarded. Managed Hyper-V hosts connect to the relay on TCP 8443, which is not forwarded through the NAT. For managed hosts on other machines, attach the VM to an External switch they can route to.

Administrator rights

A local Administrator on the Hyper-V host. The script creates VMs, switches, NAT, firewall rules and port proxies, and writes to C:\ProgramData.
No domain rights and no Azure rights are needed.
Inside the VM, the script uses the cloudgrange user and sudo, over the one-time SSH key it generated. It deletes the key at the end unless you pass -KeepInstallerSshKey.

Internet or offline bundle

Online (-Mode Online, the default). The host and the VM need outbound HTTPS to:

Endpoint	For
`cloud-images.ubuntu.com`	The Ubuntu 24.04 cloud image and its `SHA256SUMS` (from the host)
Ubuntu package mirrors	First-boot packages (`openssh-server`, `qemu-guest-agent`) (from the VM)
`get.k3s.io`, `github.com`	The K3s installer script and the pinned K3s release (from the VM)
`get.helm.sh`	Helm v3.22.0 and its checksum (from the VM)
`ghcr.io`, `docker.io`, `quay.io`	Container images. See Network egress
`qemu.weilnetz.de`	Only with `-InstallPinnedQemu` (from the host)

Offline. The Windows script cannot yet do an offline K3s install. -Engine K3s -Mode Bundled stops with CG-INST-ERR-013. -Mode Bundled on its own falls back to the legacy Docker Compose engine (see Bundled install), which is being retired. For a fully offline install on Hyper-V today, use the VHDX appliance. For an offline install on Linux, use the Linux script with its bundled images.

Full walkthrough: Online install.

See current product and release status.