ComputeDisks and imagesfield-manual-completefield-manualoperator-field-manual
VM image version
A VM image version is the exact build you ask Azure to use after you have chosen the publisher, offer, and SKU. If SKU is the edition, version is the build number or latest marker. It decides whether today and tomorrow create the same machine or whatever image the publisher currently exposes. For learning labs, latest may be convenient. For production, a pinned version usually gives better change control, rollback confidence, and audit evidence. That choice is operationally visible.
image version, VM image build, Marketplace image version, imageReference version, Compute Gallery image version
Difficulty
intermediate
CLI mappings
5
Last verified
2026-05-28
Microsoft Learn
A VM image version is the build identifier used with publisher, offer, and SKU to select a specific virtual machine image. It can be pinned to a concrete version for repeatability or set to latest when the deployment should consume the newest available build.
Technically, version is the fourth component in the Marketplace image URN: publisher:offer:sku:version. It appears as imageReference.version in ARM, Bicep, Terraform, Azure CLI, and scale set models. In Azure Compute Gallery, image versions also represent replicated, shareable builds under an image definition. The concept sits in the compute image lifecycle, connecting image discovery, golden-image publishing, regional replication, VM creation, scale set upgrades, patch baselines, and incident rollback. It also anchors image governance to a concrete build.
Why it matters
VM image version matters because it controls repeatability. A template that uses latest can quietly deploy a newer operating-system build next week, which may change packages, agents, security defaults, or boot behavior. A pinned version makes builds reproducible, supports rollback, and gives auditors a concrete baseline. Versioning also matters for migration and fleet operations: teams can canary a new image, measure extension success, then promote it across scale sets. Without version discipline, production incidents become harder to explain because nobody can prove which base build actually started the failing VM. That proof narrows incidents and makes rollback decisions faster under pressure.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In Azure CLI image discovery, az vm image list returns version values after publisher, offer, and SKU have narrowed the Marketplace image during release review.
Signal 02
In ARM, Bicep, or Terraform, imageReference.version is often pinned to a build number or set to latest for convenience before production image rollout approval.
Signal 03
In Azure Compute Gallery, image versions appear under image definitions with target regions, replica counts, and publishing or deprecation metadata during rebuild or rollback analysis.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Pin a known-good Marketplace image build so VM deployments stay reproducible across releases.
Canary a new base image version before replacing a production scale set fleet.
Rollback to a previous gallery image version after an agent, driver, or boot regression.
Track image versions used by live VMs during vulnerability response and compliance audits.
Retire old gallery versions to reduce storage cost and prevent unsupported builds from spreading.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Online education platform restores deterministic VM builds
Online education platform restores deterministic VM builds: Pinned image versions make VM fleets teachable, supportable, and recoverable when consistency matters.
📌Scenario
An online education platform rebuilt classroom lab VMs daily, but using latest caused different base images across courses and confused instructors during exams.
🎯Business/Technical Objectives
Make classroom lab VMs identical for each course cohort.
Allow tested image refreshes without surprising instructors.
Reduce failed extension installs during morning provisioning.
Keep rollback images available until exam periods ended.
✅Solution Using VM image version
The cloud engineering team replaced latest image references with pinned VM image versions in Bicep modules. CLI jobs listed available versions for each approved SKU, then promoted one build into a course-specific catalog after smoke tests. The pipeline created a small lab pool, verified domain join, monitoring, browser setup, and learning software installation, then updated production modules. Older working versions stayed approved until the cohort finished. Release notes captured the image version, extension versions, and rollback command so support staff could respond quickly during exam mornings. The release record kept approved version, test evidence, rollback version, owner, exception reason, and retirement date.
📈Results & Business Impact
Lab build variance dropped to zero across 14 active courses.
Morning provisioning failures fell from 11 percent to under 2 percent.
Rollback time for image-related issues dropped from hours to 18 minutes.
Instructor support tickets during exams decreased by 46 percent.
💡Key Takeaway for Glossary Readers
Pinned image versions make VM fleets teachable, supportable, and recoverable when consistency matters.
Case study 02
Logistics carrier uses gallery versions for driver validation
Logistics carrier uses gallery versions for driver validation: Gallery image versions give teams a release vehicle for base images, not just a place to store disks.
📌Scenario
A logistics carrier ran route-optimization services on GPU VMs, and a new base image changed driver behavior during overnight planning.
🎯Business/Technical Objectives
Validate GPU drivers before fleet-wide VM replacement.
Promote image versions through test, staging, and production.
Keep previous gallery versions replicated for emergency rollback.
Reduce planning delays caused by untested base-image updates.
✅Solution Using VM image version
The infrastructure team moved from ad hoc managed images to Azure Compute Gallery image versions. Each monthly image build created a version with release notes, target regions, and a short end-of-life window. CLI checks confirmed replication before staging deployment. A canary batch ran optimization workloads, collected boot diagnostics, extension status, GPU metrics, and job completion time, then promoted the same version to production scale sets. When a driver regression appeared, operators rolled back the scale set model to the previous gallery version while the image pipeline rebuilt a corrected version. The release record kept approved version, test evidence, rollback version, owner, exception reason, and retirement date.
📈Results & Business Impact
Driver-related planning failures fell by 83 percent over the quarter.
Image rollback completed in 26 minutes instead of rebuilding VMs manually.
Regional replication checks prevented two failed production rollouts.
Nightly route-plan completion returned to the two-hour operations target.
💡Key Takeaway for Glossary Readers
Gallery image versions give teams a release vehicle for base images, not just a place to store disks.
Case study 03
Public research institute manages vulnerability response
Public research institute manages vulnerability response: Image version inventory turns security response from guesswork into a targeted remediation plan.
📌Scenario
A public research institute needed to prove which Linux base-image versions supported hundreds of temporary analysis VMs after a critical kernel advisory.
🎯Business/Technical Objectives
Inventory image versions used by active and scheduled VMs.
Identify workloads still built from vulnerable base images.
Refresh images without breaking reproducible research pipelines.
Provide auditors with version evidence within one business day.
✅Solution Using VM image version
The platform group used CLI inventory to collect imageReference.version from templates, scale sets, and running VMs. The vulnerable version was mapped to specific research projects, while a patched Marketplace version was tested with common scientific libraries and storage mounts. Production templates were updated to the patched version, but completed experiments retained their recorded version for reproducibility. The team also created a policy report that flagged new deployments using the retired version. Evidence packages included the old and new URNs, test results, affected project list, and remediation timestamps. The release record kept approved version, test evidence, rollback version, owner, exception reason, and retirement date.
📈Results & Business Impact
Version inventory covered 96 percent of active compute within four hours.
New deployments from the vulnerable version were blocked the same day.
Research reproducibility exceptions were documented instead of silently overwritten.
Audit response time dropped from a week to less than one day.
💡Key Takeaway for Glossary Readers
Image version inventory turns security response from guesswork into a targeted remediation plan.
Why use Azure CLI for this?
I use Azure CLI for image version work because version control needs evidence, not screenshots. CLI can list available versions for a publisher-offer-SKU combination, show the exact URN, reveal plan metadata, and feed the value directly into templates or pipeline variables. For gallery images, CLI can show replication state and target regions. A seasoned Azure engineer avoids unreviewed latest references in production unless there is a deliberate update policy. CLI makes it easy to inventory live image references, compare them against the approved catalog, and prove which build a VM or scale set consumed. It also compares gallery and Marketplace references consistently.
CLI use cases
List available versions for a publisher, offer, and SKU before selecting a production image.
Show the exact image reference used by a VM or scale set during incident review.
Create or inspect Compute Gallery image versions and verify target-region replication state.
Update a scale set model to a tested image version during a controlled upgrade.
Export live image version inventory for audit, vulnerability response, or catalog cleanup.
Before you run CLI
Confirm tenant, subscription, region, publisher, offer, SKU, and whether the image source is Marketplace or Compute Gallery.
Decide whether latest is allowed, because it trades convenience for reduced deployment determinism.
Check permissions to read images, create gallery versions, or update scale set models before running mutating commands.
Verify target-region replication for gallery versions before referencing them from production deployments.
Record the current version and rollback target before changing a scale set or shared image reference.
What output tells you
Version list output shows build identifiers available for the selected publisher, offer, SKU, and region.
Image show output confirms whether the deployment uses a pinned version or the latest alias.
Gallery version output shows publishing profile, target regions, replica counts, and end-of-life metadata.
VM instance view and model output help prove which image reference created or updates a machine.
Replication status explains deployment failures caused by a version missing from the target region.
Mapped Azure CLI commands
VM image version CLI operations
direct
az vm image list --location <region> --publisher <publisher> --offer <offer> --sku <sku> --all --output table
az vm imagediscoverCompute
az vm image show --location <region> --urn <publisher>:<offer>:<sku>:<version>
az vm imagediscoverCompute
az sig image-version list --resource-group <resource-group> --gallery-name <gallery> --gallery-image-definition <image-definition> --output table
az sig image-versiondiscoverCompute
az sig image-version show --resource-group <resource-group> --gallery-name <gallery> --gallery-image-definition <image-definition> --gallery-image-version <version>
az sig image-versiondiscoverCompute
az vmss update --resource-group <resource-group> --name <scale-set> --set virtualMachineProfile.storageProfile.imageReference.version=<version>
az vmssconfigureCompute
Architecture context
Architecturally, image version is the release marker for the base compute layer. It belongs beside application version, infrastructure template version, and configuration version in a disciplined rollout model. Marketplace versions are selected during VM creation, while Compute Gallery versions are published, replicated, and consumed by downstream workloads. In scale sets, image version choices shape upgrade strategy, instance replacement, and rollback. In regulated environments, versions are often promoted from build subscription to test, then production, with vulnerability scans, extension validation, policy review, and regional replication checks before broad use. That makes image promotion part of the normal release architecture instead of an ad hoc rebuild.
Security
Security impact is direct because version identifies the exact image build and its patch baseline at deployment time. Newer versions may contain security fixes, but they may also include changed defaults or agents that need testing. Older pinned versions are reproducible yet can become vulnerable if teams never refresh them. Track which versions are approved, scanned, and still supported. Restrict production deployments from arbitrary versions, and review latest usage carefully. For gallery images, control who can publish, replicate, or delete versions because those actions alter the trusted base for many future VMs. That control reduces silent drift in regulated compute estates.
Cost
Versioning has indirect but meaningful cost impact. Gallery versions consume storage in each replicated region, and keeping too many old builds increases storage and management overhead. Marketplace latest usage may reduce manual maintenance, but it can create expensive incidents if an untested build causes failed rollouts. Pinned versions can also slow security remediation, increasing operational risk. FinOps and platform teams should define retention for gallery versions, clean unused builds, and avoid rebuilding fleets unnecessarily. A controlled version policy reduces wasted compute hours during failed deployments and lowers investigation effort. That discipline avoids paying for storage and rebuilds no workload still needs.
Reliability
Reliability improves when image versions are deliberate. Pinning known-good versions prevents surprise behavior during redeployments, disaster recovery, and scale-out. At the same time, staying pinned forever can preserve bugs or unsupported guest agents. Reliable architecture uses canaries, staged promotion, and rollback to a previous image version. For Compute Gallery, confirm the version has replicated to all required regions before deployments depend on it. For scale sets, pair image version changes with health monitoring, upgrade domains, and a clear decision about automatic versus manual image upgrades. This keeps recovery evidence aligned with the version that actually booted. It also gives rollback tests a precise target.
Performance
Performance can change between image versions because publishers update kernels, drivers, agents, packages, initialization scripts, and security settings. A newer version may boot faster or include better drivers, while another may increase startup time or conflict with an extension. For gallery images, replication placement and version availability affect deployment speed in each region. Benchmark the exact version selected for production, especially before scale set upgrades or migration waves. Capture boot diagnostics, provisioning duration, extension timing, and workload benchmarks so version changes are measured rather than guessed. Those measurements prevent teams from blaming the application for image-level regressions during rollout testing.
Operations
Operators use image versions during release planning, incident reconstruction, vulnerability response, and VM replacement. They list versions, check which one a template references, compare live VMs against the intended baseline, and update image catalogs after testing. Good operations practice means recording version ownership, publish date, scan evidence, target regions, and deprecation plan. During outages, knowing the image version helps separate guest-image problems from extension, application, or networking problems. During audits, it proves the exact base build used by production machines. Those records turn base images into managed releases rather than background infrastructure that changes quietly. They also help support teams correlate incidents with the build that introduced them.
Common mistakes
Using latest in production without a canary, rollback plan, or change record.
Assuming a version available in the build region is already replicated to every target region.
Deleting old gallery versions before confirming no scale set, template, or recovery plan references them.
Treating image version changes as patching only, even though drivers and agents can also change.
Investigating provisioning failures without checking whether the expected version still exists.