Skip to content

fix(api): make user-facing condition messages clearer#2558

Draft
fl64 wants to merge 25 commits into
mainfrom
fix/api/user-friendly-condition-messages
Draft

fix(api): make user-facing condition messages clearer#2558
fl64 wants to merge 25 commits into
mainfrom
fix/api/user-friendly-condition-messages

Conversation

@fl64

@fl64 fl64 commented Jun 30, 2026

Copy link
Copy Markdown
Member

Description

Status conditions on virtualization resources sometimes described a problem in terms the user cannot see or act on — launcher and migration pods, storage volume claims, internal virtualization objects, image-registry internals — or used awkward, sometimes ungrammatical wording. This reworks the .status.conditions[].message texts across VirtualMachine, VirtualMachineBlockDeviceAttachment, VirtualDisk, VirtualImage, ClusterVirtualImage, VirtualDiskSnapshot and VirtualMachineSnapshot so each message describes the current state in terms of the resources a user actually works with.

Only the message wording changes. Condition types, reasons, statuses and all reconcile behaviour stay the same. This PR covers the text-only changes; messages that still relay a raw internal error will be cleaned up separately.

Why do we need it, and what problem does it solve?

A user reads a resource's status to understand what is happening with it. When a VirtualMachine is stuck or a disk or image is not ready, a message that points at a pod, a storage volume claim or an internal object gives no actionable signal and exposes implementation details the user has no control over. Clear, self-explanatory messages let users troubleshoot on their own and read straight into the module's release notes.

What is the expected result?

kubectl describe on these resources shows user-facing wording, for example:

  • Virtual disk "vd1" is waiting for its storage to be provisioned (was: … underlying PVC to be bound);
  • Migration is in progress: preparing the migration target (was: … target pod is being scheduled and prepared);
  • VirtualMachine "x" is not fully started yet (was: InternalVirtualizationVirtualMachineInstance "x" not found);
  • The image is being imported (was: Import is in the process of provisioning to DVCR).

Behaviour is unchanged: reasons and statuses are the same, so anything that keys on them is unaffected.

Checklist

  • The code is covered by unit tests.
  • e2e tests passed.
  • Documentation updated according to the changes.
  • Changes were tested in the Kubernetes cluster manually.

Changelog entries

section: vm
type: fix
summary: VirtualMachine status messages are clearer and no longer expose internal implementation details.
---
section: vmbda
type: fix
summary: VirtualMachineBlockDeviceAttachment status messages are clearer and no longer expose internal implementation details.
---
section: vd
type: fix
summary: VirtualDisk status messages are clearer and no longer expose internal implementation details.
---
section: vi
type: fix
summary: VirtualImage status messages are clearer and no longer expose internal implementation details.
---
section: cvi
type: fix
summary: ClusterVirtualImage status messages are clearer and no longer expose internal implementation details.
---
section: vdsnapshot
type: fix
summary: VirtualDiskSnapshot status messages have clearer wording.
---
section: vmsnapshot
type: fix
summary: VirtualMachineSnapshot status messages have clearer wording.

Reword VirtualMachine status condition messages so they describe the
state in user terms and stop leaking internals: drop launcher pod
wording from migration progress, replace the underlying PVC reference
with disk storage, fix agent/provisioning wording and use full resource
name with quoted disk names.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
fl64 added 17 commits June 30, 2026 12:41
Reword VirtualMachineBlockDeviceAttachment status messages to describe
the state in user terms: drop InternalVirtualization* and underlying
PVC/PersistentVolume wording in favour of the VirtualMachine and the
disk/image storage, fix grammar and the limit message.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Reword VirtualDisk status messages to describe provisioning in user
terms: drop pvc importer / PVC provisioner / StorageProfile wording in
favour of disk provisioning and StorageClass, and stop printing internal
PVC/PV object names.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Reword VirtualImage status messages to user terms: replace DVCR/PVC
provisioner and importer/bounder pod wording with image import and disk
storage, drop the internal registry URL, use the full StorageClass/
PersistentVolumeClaim names and fix grammar.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Reword ClusterVirtualImage status messages to user terms: replace DVCR
provisioner and PVC wording with image provisioning and snapshot volume
restore, drop the internal registry URL, and fix the upload-wait text.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Fix grammar and a typo in VirtualDiskSnapshot status messages and stop
referencing the internal volume snapshot object.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Fix grammar in VirtualMachineSnapshot status messages ("was not found",
"in the process of deletion").

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
The attach-precondition messages now state that the VirtualMachine is
not running, instead of implying it is mid-start, which is misleading
for a stopped machine and inconsistent with the rest of the wording.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Keep the node name where the disk storage is missing: it is the
actionable detail an operator needs to debug the attachment, and the
node is a public object the user can inspect.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Use the same user-facing wording for the same state across VirtualImage
and ClusterVirtualImage: image import preparing/in-progress and the
image-no-longer-available message now read identically.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Use one consistent vocabulary for storage states across disk, image and
attachment resources: name the PersistentVolumeClaim/PersistentVolume in
full (never PVC/PV abbreviations), say disk/image storage where the
object is incidental, and use "ready" instead of the Bound phase term
in storage phrasing. Also fixes two VirtualImage messages that still
read PVC and leaked the internal claim name.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Replace the vague "Waiting for the image storage to be ready" with the
concrete "Waiting for the PersistentVolumeClaim to be Bound": the PVC is
a public object the user can inspect, and the phase is its real status.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Consistency pass over the reworded messages: say "guest agent version",
"StorageClass" and the "Bound" phase uniformly, use the same text for
the same state across VirtualImage and ClusterVirtualImage, and name the
PersistentVolumeClaim in the snapshot-restore wait instead of a vague volume.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
A missing backing volume (PVC absent) was reported with the same
"storage is not ready" wording as a not-yet-bound one, hiding that the
storage is actually gone. Say it was not found instead.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Text-only cleanups (no logic change): full resource names (VirtualMachineClass,
VirtualMachineIPAddress), correct IP-address casing/grammar, trailing periods,
migration progress in user terms (node/VirtualMachine instead of target pod),
clearer snapshot/operation wording, and name the VolumeSnapshot when it is lost.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Restore the PersistentVolumeClaim/PersistentVolume/VolumeSnapshot name in
the *Lost messages: these are public objects (kubectl get pv/pvc/
volumesnapshot) and the name is the actionable detail when one is missing
— dropping it loses debuggability. Also align the VirtualImage
StorageProfile-missing text with VirtualDisk (StorageClass wording).

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
The in-progress migration messages wrongly invented "destination node"
wording. Align them with the actual KubeVirt migration phases and with
the VirtualMachine controller wording: scheduling/preparing the migration
target, source and target are being synchronized, resumed on the target,
suspended on the source.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Comment thread images/virtualization-artifact/pkg/controller/vd/internal/source/sources.go Outdated
Comment thread images/virtualization-artifact/pkg/controller/vdsnapshot/internal/life_cycle.go Outdated
fl64 added 4 commits June 30, 2026 15:18
- USBDevice/NodeUSBDevice: drop reconcile internals (NodeUSBDevice condition, USBIP ports, speed) in favour of user terms
- VMSOP: rewrite broken English, name the VirtualMachineSnapshot, describe the clone in user terms
- dvcr-gc: explain the garbage-collection postpone without the 'create provisioner' internal

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
…e storage'

When a VirtualImage is stored on a PVC, the provisioning message said 'Preparing the image storage.' — vague and inconsistent with the next state 'Importing data into the PersistentVolumeClaim.'. Name the PersistentVolumeClaim being prepared so the message reflects what actually happens.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
…nstance gap

These branches are reached only after the VirtualMachineReady condition is True (VM confirmed Running with its instance present). A subsequent nil read of the underlying instance is a transient gap, not a stopped VM. Saying 'is not running' contradicted both the VM phase and the sibling readiness handler. Align the wording: the VirtualMachine is Running, its underlying instance is just not ready yet.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
…ages

- vd: 'PV is being exported' -> full name 'The PersistentVolume is being exported.'
- vi: name and punctuate the PVC-bound wait ('Waiting for the PersistentVolumeClaim to be Bound.'); kept name-less because pvc may be nil on this branch (the %q in the suggestion would render empty/panic)
- vdsnapshot: the snapshot-of-disk wait interpolated the snapshot's own name; use spec.virtualDiskName so %q is the disk

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
@fl64 fl64 added this to the v1.10.0 milestone Jun 30, 2026
The condition message kept its trailing period (user-facing), but the same string was reused for errors.New, which ST1005 flags. Split them: period for the status message, a plain lowercase Go error for the return.

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
prismagod
prismagod previously approved these changes Jun 30, 2026
- guest agent not responding / version unsupported: tell the user to install/start/update the agent in the guest OS
- VirtualMachineClass not found: advise specifying an existing class in spec.virtualMachineClassName (full resource name, period)
- sizing-policy mismatch: drop the doubled prefix, lead with the VirtualMachine, keep the concrete details and existing guidance

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
- disks: state the ReadWriteMany requirement in user terms and point to the StorageClass to check (no false promise that RWX is available)
- non-migratable device: drop the kubevirt 'host devices' jargon and the USB-implying wording (USB is migratable); state the block plainly and advise removing the offending device

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants