✨ Add vm.spec.guestID API and its implementation

[dilyar85]

What does this PR do, and why is it needed?

This PR includes the following changes:

• A new vm.spec.guestID API in v1alpha3 and related conversion in v1alpha1 and v1alpha2.
  • Also add the missing instanceUUID conversion in v1a1
• Doc updates for this new API.
• Deploy a VM with configSpec.guestID if it's set in the VM Spec.
• Reconfigure a VM with the updated guestID (different from VM's ConfigInfo) before powering it on.
• Disallow updating vm.spec.guestID if a VM is powered on.
• Tests to cover all the above implementations.

Depending on if a VM has been created, the VM's condition will be updated when an unsupported guestID is specified:

• If the VM has not yet been created, the VirtualMachineCreated condition will be marked as false with a message indicating an invalid guestID.
• If the VM has been created, the GuestIDReconfigured condition will be marked as false. It will be marked as true when a valid guestID is passed afterwards.

Testing Done:

• Valid Guest ID:

# Deploy a VM with spec.guestID set:
$ cat << EOF | kubectl apply -f -
apiVersion: vmoperator.vmware.com/v1alpha3
kind: VirtualMachine
metadata:
   name: test-vm-guest-id
   namespace: sdiliyaer-test
spec:
   className: best-effort-small
   imageName: ubuntu-impish-21.10-cloudimg
   storageClass: wcpglobal-storage-profile
   guestID: otherGuest64
EOF
virtualmachine.vmoperator.vmware.com/test-vm-guest-id created

# VM has the expected configSpec.guestID set:
$ govc vm.info -json test-vm-guest-id | jq '.virtualMachines[].config.guestId'
"otherGuest64"

# Update the guestID when VM is powered on (should be denied):
$ cat << EOF | kubectl apply -f -
apiVersion: vmoperator.vmware.com/v1alpha3
kind: VirtualMachine
metadata:
  name: test-vm-guest-id
  namespace: sdiliyaer-test
spec:
  className: best-effort-small
  imageName: ubuntu-impish-21.10-cloudimg
  storageClass: wcpglobal-storage-profile
  guestID: ubuntu64Guest
EOF
...
error when patching "STDIN": admission webhook "default.validating.virtualmachine.v1alpha3.vmoperator.vmware.com" denied the request: spec.guestID: Forbidden: updates to this field is not allowed when VM power is on

# Update the guestID when VM is powered off (should be allowed):
$ cat << EOF | kubectl apply -f -
apiVersion: vmoperator.vmware.com/v1alpha3
kind: VirtualMachine
metadata:
  name: test-vm-guest-id
  namespace: sdiliyaer-test
spec:
  className: best-effort-small
  imageName: ubuntu-impish-21.10-cloudimg
  storageClass: wcpglobal-storage-profile
  guestID: ubuntu64Guest
  powerState: PoweredOff
EOF
virtualmachine.vmoperator.vmware.com/test-vm-guest-id configured

# Power on the VM and confirm VM has the updated guestID:
$ govc vm.info -json test-vm-guest-id | jq '.virtualMachines[].config.guestId'\
"ubuntu64Guest"

# Confirm the VM has the expected guestID reconfigured condition set:
$ kubectl get vm -n sdiliyaer-test test-vm-guest-id -o json | jq '.status.conditions[] | select(.type == "GuestIDReconfigured")'
{
  "lastTransitionTime": "2024-06-13T18:16:31Z",
  "message": "",
  "reason": "True",
  "status": "True",
  "type": "GuestIDReconfigured"
}

• Invalid Guest ID:

# Deploy a new VM with an invalid guestID:
$ kubectl get vm -n sdiliyaer-test test-vm-guest-id-invalid-2 -o json | jq '.status.conditions[] | select(.type == "VirtualMachineCreated")'
{
  "lastTransitionTime": "2024-06-13T18:19:38Z",
  "message": "deploy error: An invalid argument \"configSpec.guestId\" was specified.",
  "reason": "Error",
  "status": "False",
  "type": "VirtualMachineCreated"
}

# Update an existing VM with an invalid guestID:
$ kubectl get vm -n sdiliyaer-test test-vm-guest-id-invalid-2 -o json | jq '.status.conditions[] | select(.type == "GuestIDReconfigured")'
{
  "lastTransitionTime": "2024-06-13T18:21:46Z",
  "message": "The specified guest ID value is not supported: otherGuestInvalid",
  "reason": "Invalid",
  "status": "False",
  "type": "GuestIDReconfigured"
}

# Update the VM with a valid guestID:
$ kubectl get vm -n sdiliyaer-test test-vm-guest-id-invalid-2 -o json | jq '.status.conditions[] | select(.type == "GuestIDReconfigured")'
{
  "lastTransitionTime": "2024-06-13T18:23:24Z",
  "message": "",
  "reason": "True",
  "status": "True",
  "type": "GuestIDReconfigured"
}

Are there any special notes for your reviewer:

A separate change has been submitted internally to the vSphere Content Library service to avoid overwriting the VM's guestID from the OVF template.

Please add a release note if necessary:

Introduce `vm.spec.guestID` API to specify a VM's guest operating system identifier.

---

📚 Documentation preview 📚: https://vm-operator--563.org.readthedocs.build/en/563/

[bryanv]

I'm a little uneasy that this condition exposes an internal implementation detail. In a lot of cases we don't need that reconfigure b/c of the 7605 work, and ideally I want to get us to where the VM is created with its desired configuration in all cases. And with resize coming that is going to take the place of the current prepower on reconfigure, and that will have its own conditon.

[dilyar85]

The purpose of this new condition is to inform users when they attempt to deploy a VM with an invalid guestID, as it's no longer verified by a generated list from the imported govmomi package. While implementing this change, I thought why make it specific to guestID only, hence the PrePowerOnReconfigureReady name above to expose any VM reconfigure failure (it still has config.guestID in the condition's reason if the task fails by that).

On the other hand, today VMOP already sends a K8s event if the PrePowerOnReconfigure task fails. This event contains specific invalid configs as well, such as guestID shown in the following example. So I think users are not entirely in the dark if they have specified an unsupported guestID:

Warning  CreateOrUpdateFailure  29s (x16 over 116s)  vmware-system-vmop/vmware-system-vmop-controller-manager-745fcd885b-v2xhm/virtualmachine-controller  reconfigure VM task failed: A specified parameter was not correct: configSpec.guestId

@akutz Any thoughts on dropping this condition and leveraging existing K8s events for this?

[sreyasn]

I'd prefer to not start exposing prePowerOnReconfigure as a condition too.

[dilyar85]

Updated with the Guest ID specific condition. Please refer to the PR's description for all possible success/failure cases.

[dougm]

lgtm, just some minor doc suggestions.

[dougm]

lgtm

[github-actions]

Package	Line Rate	Health
github.com/vmware-tanzu/vm-operator/controllers/contentlibrary/clustercontentlibraryitem	81%	➖
github.com/vmware-tanzu/vm-operator/controllers/contentlibrary/contentlibraryitem	85%	➖
github.com/vmware-tanzu/vm-operator/controllers/contentlibrary/utils	97%	✔
github.com/vmware-tanzu/vm-operator/controllers/infra/configmap	71%	❌
github.com/vmware-tanzu/vm-operator/controllers/infra/node	77%	❌
github.com/vmware-tanzu/vm-operator/controllers/infra/secret	77%	❌
github.com/vmware-tanzu/vm-operator/controllers/util/encoding	73%	❌
github.com/vmware-tanzu/vm-operator/controllers/virtualmachine	87%	➖
github.com/vmware-tanzu/vm-operator/controllers/virtualmachineclass	75%	❌
github.com/vmware-tanzu/vm-operator/controllers/virtualmachinepublishrequest	81%	➖
github.com/vmware-tanzu/vm-operator/controllers/virtualmachinereplicaset	68%	❌
github.com/vmware-tanzu/vm-operator/controllers/virtualmachineservice	83%	➖
github.com/vmware-tanzu/vm-operator/controllers/virtualmachineservice/providers	92%	✔
github.com/vmware-tanzu/vm-operator/controllers/virtualmachinesetresourcepolicy	80%	➖
github.com/vmware-tanzu/vm-operator/controllers/virtualmachinewebconsolerequest/v1alpha1	72%	❌
github.com/vmware-tanzu/vm-operator/controllers/virtualmachinewebconsolerequest/v1alpha1/conditions	88%	➖
github.com/vmware-tanzu/vm-operator/controllers/virtualmachinewebconsolerequest/v1alpha1/patch	78%	❌
github.com/vmware-tanzu/vm-operator/controllers/virtualmachinewebconsolerequest/v1alpha2	73%	❌
github.com/vmware-tanzu/vm-operator/controllers/volume	86%	➖
github.com/vmware-tanzu/vm-operator/pkg/builder	95%	✔
github.com/vmware-tanzu/vm-operator/pkg/conditions	88%	➖
github.com/vmware-tanzu/vm-operator/pkg/config	100%	✔
github.com/vmware-tanzu/vm-operator/pkg/config/env	100%	✔
github.com/vmware-tanzu/vm-operator/pkg/patch	78%	❌
github.com/vmware-tanzu/vm-operator/pkg/prober	91%	✔
github.com/vmware-tanzu/vm-operator/pkg/prober/probe	91%	✔
github.com/vmware-tanzu/vm-operator/pkg/prober/worker	77%	❌
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere	75%	❌
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/client	80%	➖
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/clustermodules	71%	❌
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/config	72%	❌
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/contentlibrary	72%	❌
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/credentials	100%	✔
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/network	80%	➖
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/placement	77%	❌
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/session	76%	❌
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/sysprep	100%	✔
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/vcenter	82%	➖
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/virtualmachine	74%	❌
github.com/vmware-tanzu/vm-operator/pkg/providers/vsphere/vmlifecycle	68%	❌
github.com/vmware-tanzu/vm-operator/pkg/record	78%	❌
github.com/vmware-tanzu/vm-operator/pkg/topology	92%	✔
github.com/vmware-tanzu/vm-operator/pkg/util	85%	➖
github.com/vmware-tanzu/vm-operator/pkg/util/cloudinit	89%	✔
github.com/vmware-tanzu/vm-operator/pkg/util/cloudinit/validate	91%	✔
github.com/vmware-tanzu/vm-operator/pkg/util/image	100%	✔
github.com/vmware-tanzu/vm-operator/pkg/util/kube	81%	➖
github.com/vmware-tanzu/vm-operator/pkg/util/ptr	100%	✔
github.com/vmware-tanzu/vm-operator/pkg/util/resize	98%	✔
github.com/vmware-tanzu/vm-operator/pkg/util/vmopv1	90%	✔
github.com/vmware-tanzu/vm-operator/pkg/util/vsphere/client	68%	❌
github.com/vmware-tanzu/vm-operator/pkg/util/vsphere/vm	80%	➖
github.com/vmware-tanzu/vm-operator/pkg/webconsolevalidation	100%	✔
github.com/vmware-tanzu/vm-operator/webhooks/common	100%	✔
github.com/vmware-tanzu/vm-operator/webhooks/persistentvolumeclaim/validation	95%	✔
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachine/mutation	86%	➖
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachine/validation	95%	✔
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachineclass/mutation	62%	❌
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachineclass/validation	89%	➖
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachinepublishrequest/validation	92%	✔
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachinereplicaset/validation	90%	✔
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachineservice/mutation	67%	❌
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachineservice/validation	92%	✔
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachinesetresourcepolicy/validation	89%	✔
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachinewebconsolerequest/v1alpha1/validation	92%	✔
github.com/vmware-tanzu/vm-operator/webhooks/virtualmachinewebconsolerequest/v1alpha2/validation	92%	✔
Summary	81% (7960 / 9818)	➖

Minimum allowed line rate is 79%