Virt-Operator Deployment Reconciliation#

virt-operator determines whether a KubeVirt installation needs to be created or updated by computing a deployment ID — a SHA-1 hash over all meaningful configuration properties — and comparing it against the state stored on the KubeVirt CR. Every reconcile loop uses this ID to decide whether to trigger a new install-strategy job, update component deployments/DaemonSets, or declare the system converged.

KubeVirtDeploymentConfig and the Deployment ID#

The central data structure is KubeVirtDeploymentConfig, which holds:

• Registry, ImagePrefix, KubeVirtVersion, Namespace — top-level deployment coordinates
• ComponentImages — an embedded struct with per-component image references (operator, API, controller, handler, launcher, export proxy/server, sidecar shim, etc.) 1
• AdditionalProperties — a map[string]string for values sourced from KubeVirtSpec (pull policy, pull secrets, product metadata, feature-gate flags, etc.) 2
• PassthroughEnvVars — extra env vars forwarded from the operator pod 3

The ID is computed in generateInstallStrategyID(), which hashes the output of getStringFromFields() using SHA-1 (used as a non-cryptographic fingerprint, not for security). After construction, the ID is written to KubeVirt.Status.TargetDeploymentID via SetTargetDeploymentConfig().

How the ID Drives Reconciliation#

Three mechanisms consume the deployment ID:

1. Upgrade detection — isUpdating() in pkg/virt-operator/kubevirt.go 4 returns true when ObservedDeploymentID != TargetDeploymentID. This comparison gates the entire update flow.

2. Install-strategy-identifier annotation — every managed Kubernetes object (Deployments, DaemonSets, Pods) gets the ID injected as the v1.InstallStrategyIdentifierAnnotation annotation via injectOperatorMetadata() 5. Reconciliation skips objects whose annotation already matches the target ID 6.

3. Pod up-to-date check — PodIsUpToDate() returns true only if the pod's InstallStrategyIdentifierAnnotation, InstallStrategyVersionAnnotation, and InstallStrategyRegistryAnnotation all match the current target. Stale pods (mismatched ID) are treated as needing replacement.

Reflection-Based String Serialization#

getStringFromFields() delegates to fieldsToString(), which walks the struct via reflect.Value, appending each field's name and value:

Key detail: AdditionalProperties keys are sorted before serialization 7 to ensure map iteration order doesn't produce different IDs for the same configuration. An empty ImagePrefixKey entry is also stripped before hashing to normalize "" and absent keys to the same ID 8.

Bug: reflect.Value.String() on Struct Fields (Fixed in PR #16791)#

Before PR #16791, getStringFromFields() had no reflect.Struct branch. For any non-map field, it called v.Field(i).String() directly. In Go, calling .String() on a reflect.Value whose kind is reflect.Struct does not return the struct's contents — it returns a constant type-descriptor string like <util.ComponentImages Value> 9.

This became a critical bug after commit e80193d263 moved the individual image fields from flat fields on KubeVirtDeploymentConfig into the embedded ComponentImages struct. All 11 image fields (VirtOperatorImage, VirtApiImage, VirtControllerImage, VirtHandlerImage, VirtLauncherImage, VirtExportProxyImage, VirtExportServerImage, VirtSynchronizationControllerImage, GsImage, PrHelperImage, SidecarShimImage) were silently omitted from the hash. Changing any VIRT_*_IMAGE env var on the operator did not produce a new deployment ID, so the operator reused stale install-strategy ConfigMaps and syncDeployment() detected no diff, skipping the rollout entirely 9.

The fix added the reflect.Struct case in fieldsToString() with a recursive call, and added a default: panic(...) to catch future omissions 10.

Related Bug: CustomizeComponents and the Deployment ID (PR #18133)#

A similar problem exists with spec.customizeComponents: getKVMapFromSpec() 11 calls v.Field(i).String() on each KubeVirtSpec field. The CustomizeComponents field is a struct, so it too produces a constant type-descriptor. Changing spec.customizeComponents alone does not alter the deployment ID, meaning PodIsUpToDate() will not flag existing pods as stale and the canary rollout phases are bypassed entirely 12.

PR #18133 worked around this in the canary upgrade test by switching the test trigger to spec.productVersion — a plain string field that does flow through AdditionalProperties and does mutate the hash. This is a test-level workaround; the production gap (CustomizeComponents changes not triggering a rollout) remains a known issue flagged for follow-up 12.

Key Files#