Prerequisites — VHDX appliance

The appliance is a prepared Ubuntu virtual disk (VHDX) that already contains K3s, the CloudGrange Helm chart and every container image. You import it into Hyper-V, it starts, and you finish in the web setup wizard. It is for customers who want CloudGrange without administering Linux or Kubernetes.

The appliance is a managed foundation. CloudGrange owns its Foundation: the Ubuntu operating system and its updates, K3s and the host services. CloudGrange delivers those updates through the Foundation card in Platform → Updates, and an administrator always starts them. See Updates and Support boundary.

CloudGrange is in active development and is not GA. The current lab appliance build carries no signature file and is imported with -AllowUnsigned; its VHDX is verified against its SHA-256. See current product and release status.

Hyper-V host

Requirement Detail
Hyper-V The Hyper-V role (Windows Server) or feature (Windows client), with its PowerShell module
PowerShell PowerShell 7, run as Administrator. Import-CloudGrangeAppliance.ps1 declares #Requires -Version 7.0 and -RunAsAdministrator
VM generation Generation 2 with Secure Boot on, using the MicrosoftUEFICertificateAuthority template. The host must support Generation 2 VMs
Integration services Key-Value Pair Exchange, which the import script enables. The appliance uses it to pass its address and one-time setup credentials to the host

VM resources

The import script creates the VM with these settings:

Setting Value
vCPU 2
Memory Dynamic: 4 GB at startup, 2 GB minimum, 8 GB maximum
Disk The imported VHDX, dynamically expanding. It is built from CloudGrange's Windows-script VM, which has a 30 GB virtual disk
Start and stop Starts automatically with the host (30-second delay) and shuts down with it

The CloudGrange workloads in the chart set memory limits that total about 5.4 GiB, so make sure the host can grant the full 8 GB maximum. You can change the vCPU count and memory in Hyper-V Manager after import.

Host storage: enough free space for the extracted VHDX and its growth up to its maximum size, plus the downloaded archive while you extract it. The 2609.0.0-preview.26 archive is 3.2 GB and expands to a 6.2 GB VHDX, so plan for about 40 GB free. Import-CloudGrangeAppliance.ps1 does not check free space.

Virtual switch

The VM connects to one Hyper-V virtual switch, -SwitchName, which defaults to cloudgrange-external.

  • Existing switch. If a switch with that name exists, the script uses it and does not change it. Use an External switch bound to your LAN when users and managed Hyper-V hosts must reach the appliance directly.
  • No switch. If the switch does not exist, the script creates an Internal switch with that name. An internal switch has no DHCP server and no outbound NAT, so give the VM a static address (see below), and remember that the appliance is then reachable only from the host and through the host's port forward.

IP plan

Option How
DHCP (default) The appliance requests an address on the switch's network. It reports its address to the host over KVP
Static Pass -VmIp, -PrefixLength (default 24), -Gateway and -DnsServers. The script writes a network-only cloud-init seed ISO

Plan these addresses:

  • One IPv4 address for the appliance, reserved in DHCP or assigned statically.
  • A DNS name for it (recommended). Users browse to it, and it becomes the identity issuer. See DNS.
  • Reachability from managed hosts. CloudGrange agents on your Hyper-V hosts connect to the appliance's built-in relay on TCP 8443.

Ports:

Port Direction Purpose
443/tcp Inbound Portal, API and sign-in
8443/tcp Inbound from managed hosts Relay (agent connections)
22/tcp Inbound, optional Operator SSH with the key the import script saves

Unless you pass -SkipHostPortForward, the import script also publishes the portal on the host's port 443, using a Windows Firewall rule (CloudGrange-Portal-443) and a netsh port proxy to the VM. Only 443 is forwarded. 8443 is not. If managed hosts must reach the relay, put the appliance on a switch they can route to directly.

Internet access

None is needed to import. The VHDX carries K3s, the chart and every image. With internet access, the portal can check the CloudGrange update channel. Without it, upload release bundles manually. See Updates.

Import steps

  1. Download the appliance archive and its .sha256 file from the release, and the installer source for the same release, which contains Import-CloudGrangeAppliance.ps1.

  2. Extract both.

  3. In PowerShell 7 as Administrator, run the import script:

    .\Import-CloudGrangeAppliance.ps1 `
  -AppliancePath '<path>\cloudgrange-appliance-k3s.vhdx' `
  -VmName 'cloudgrange' `
  -SwitchName '<your-external-switch>' `
  -AllowUnsigned

    Add -VmIp 10.0.0.50 -PrefixLength 24 -Gateway 10.0.0.1 -DnsServers 10.0.0.10 for a static address.

  4. The script verifies the VHDX against its SHA-256 manifest before it creates anything. It refuses if the manifest is missing or does not match.

  5. It creates the VM, starts it, waits for first boot to finish (the appliance generates new credentials, machine identity and SSH host keys), waits for the portal, and prints the setup URL and one-time credentials.

  6. Open the URL and complete the first-run setup wizard straight away. The one-time credentials are withdrawn after setup.

Full walkthrough: Appliance install.

See current product and release status.