vSphere Hardware Version Management¶

This page is aligned to VirtRigaud v0.3.8. It describes how the vSphere provider's HardwareUpgrade gRPC RPC works, what the manager controller currently does (and does not) do with it, and what an operator needs from vCenter / ESXi for it to succeed.

What it is, in one sentence¶

vSphere VMs carry a virtual-hardware compatibility level (vmx-N, e.g. vmx-21) that gates which guest features the VM can use. VirtRigaud's vSphere provider exposes a HardwareUpgrade RPC that bumps a VM's vmx-N upward, but only upward — and only when the VM is powered off.

Source-of-truth references¶

What the RPC does¶

HardwareUpgrade(id, target_version int32) in internal/providers/vsphere/server.go:966:

1. Resolves the VM by id (a vSphere ManagedObjectReference.Value).
2. Confirms the VM is powered off. Returns "VM must be powered off for hardware upgrade, current state: <state>" if not (server.go:994-996).
3. Reads config.version to get the current vmx-N (server.go:1000-1005).
4. Computes the target as fmt.Sprintf("vmx-%d", req.TargetVersion) (server.go:1006).
5. If current == target, returns success without doing anything (server.go:1013-1017).
6. Otherwise calls isNewerHardwareVersion(current, target). If target is not strictly newer, returns "target version <X> is not newer than current version <Y>" (server.go:1020-1022). Downgrades are not supported.
7. Calls govmomi's vm.UpgradeVM(ctx, targetVersion) and waits for the task (server.go:1025-1034).

The RPC blocks until vCenter reports the upgrade task complete.

What the manager controller currently does with it¶

Hardware-version compatibility matrix¶

The mapping between vmx-N and ESXi versions is a vCenter/ESXi property, not a VirtRigaud one. VirtRigaud only asks vCenter to perform the upgrade; vCenter rejects the request if the target is not supported by the ESXi host.

A conservative subset of the matrix below — the rows VirtRigaud has been exercised against — is informative; the official VMware compatibility matrix is authoritative.

VirtRigaud does not keep its own allowlist of vmx-N values — any integer that the underlying govmomi vm.UpgradeVM call accepts will succeed.

Setting the hardware version at VM creation¶

Set extraConfig.vsphere.hardwareVersion on the VMClass. The provider reads it at create time (internal/providers/vsphere/server.go:2019):

apiVersion: infra.virtrigaud.io/v1beta1
kind: VMClass
metadata:
  name: modern-vm-class
spec:
  cpu: 4
  memoryMiB: 8192
  firmware: UEFI
  extraConfig:
    # Quoted string — the provider parses it as an integer internally.
    vsphere.hardwareVersion: "21"
  diskDefaults:
    type: thin
    sizeGiB: 50

apiVersion: infra.virtrigaud.io/v1beta1
kind: VirtualMachine
metadata:
  name: modern-vm
spec:
  providerRef:
    name: vsphere-provider
    namespace: virtrigaud-system
  classRef:
    name: modern-vm-class
  imageRef:
    name: ubuntu-22-04

If extraConfig.vsphere.hardwareVersion is unset, the provider does not pass a Version to govmomi and vCenter picks its default for the targeted ESXi.

Upgrading an existing VM out-of-band (workaround for v0.3.8)¶

This is the gRPC-direct path described above. Useful when you have a fleet of existing VMs at vmx-15 and want to bump them to vmx-21 without recreating them through the manager.

Prerequisites:

1. The VM must be powered off — set VirtualMachine.spec.powerState: Off and wait for the reconciler to confirm status.powerState: Off.
2. The destination ESXi must support the target vmx-N.
3. You need network reach to the vSphere provider's gRPC endpoint (typically provider-vsphere.virtrigaud-system.svc:9090 cluster-internally, or whatever the chart exposes).
4. You must satisfy the provider's auth requirements at the gRPC layer.

Programmatic call (Go):

package main

import (
    "context"
    "fmt"
    "log"

    providerv1 "github.com/projectbeskar/virtrigaud/proto/rpc/provider/v1"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func upgradeVMHardwareVersion(endpoint, vmID string, targetVersion int32) error {
    // NOTE: since v0.3.7 the provider enforces mTLS (#147). This insecure
    // dial only works against a lab provider explicitly opted out of TLS
    // (VIRTRIGAUD_PROVIDER_INSECURE=true). For a production provider, build
    // credentials from your client cert/key + the provider CA with
    // credentials.NewTLS(...) instead.
    conn, err := grpc.NewClient(endpoint, grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        return fmt.Errorf("dial provider: %w", err)
    }
    defer conn.Close()

    client := providerv1.NewProviderClient(conn)

    req := &providerv1.HardwareUpgradeRequest{
        Id:            vmID,                  // vSphere ManagedObjectReference.Value
        TargetVersion: targetVersion,         // e.g. 21 → "vmx-21"
    }
    resp, err := client.HardwareUpgrade(context.Background(), req)
    if err != nil {
        return fmt.Errorf("HardwareUpgrade failed: %w", err)
    }

    // The RPC blocks until vCenter completes the task.
    log.Printf("HardwareUpgrade returned: %+v", resp)
    return nil
}

The vmID is the value of VirtualMachine.status.id on the VirtRigaud VirtualMachine CR (it mirrors the vSphere managed-object-reference value).

Operational guidance¶

• Snapshot first. vCenter's own upgrade flow recommends a snapshot. You can use the VMSnapshot CR to create one through VirtRigaud before invoking the RPC.
• Be conservative. Pick the lowest vmx-N your guest OS and the destination ESXi support. Bumping to vmx-21 on a cluster that still has some 7.0 ESXi hosts will prevent that VM from running on the older hosts.
• One-way. Once upgraded, you cannot downgrade through this RPC. The vCenter UI also does not offer a downgrade path; you'd need to clone the VM to a new VM at the lower version.
• Verify after upgrade. kubectl get vm <name> -o jsonpath='{.status.provider}' surfaces what the provider reported back. The authoritative source is config.version in vCenter.

Troubleshooting¶

Cross-references¶

• Providers / vSphere — overall vSphere provider documentation, including authentication, datastore selection, and capability flags.
• Provider Capabilities Matrix — what each provider can and cannot do.
• Resilience — what happens when the vSphere session is unhealthy (the CircuitBreaker takes the provider offline cleanly).
• Operations / Security — credential flow into the vSphere provider and what compensations are needed because gRPC auth is not wired.