Compute Disks and images premium

Gallery image version

Gallery image version is a specific published version of a gallery image that virtual machines and scale sets can use as their source. Teams use it to roll out tested OS and application baselines with version numbers, regional replication, retirement dates, and rollback options. In daily Azure work, it appears when engineers promote a golden image, deploy identical VMs across regions, retire vulnerable builds, or troubleshoot why a new VM used the wrong baseline. It is not the image family definition, a live VM, an operating system patch job, or proof that every deployed VM remains compliant after boot.

Aliases
Azure Compute Gallery image version, SIG image version, image version
Difficulty
intermediate
CLI mappings
6
Last verified
2026-05-14

Microsoft Learn

A concrete Azure Compute Gallery image artifact, under an image definition, that can be replicated and used to create VMs or scale set instances.

Microsoft Learn: Store and share images in an Azure Compute Gallery2026-05-14

Technical context

Technically, Gallery image version is configured or observed through image version number, source image or snapshot, target regions, replica counts, storage account type, exclude-from-latest flag, end-of-life date, sharing, and deployment references. Important settings include version name, source resource ID, publishing profile, regional replicas, storage type, latest version behavior, encryption, replication mode, end-of-life date, and target region availability. Operators inspect it with az sig image-version output, replication state, VM source references, build pipeline logs, vulnerability scan evidence, deployment history, Activity Log entries, and gallery replication metrics.

Why it matters

Gallery image version matters because it turns design intent into production behavior. When teams misunderstand it, they may deploy to the wrong place, expose credentials, overpay for capacity, break scaling, create inconsistent VM builds, or hide storage risk behind a vague name. For this term, that means versioned images let teams deploy and roll back VM baselines predictably instead of relying on mutable, undocumented source machines. It affects security, reliability, operations, cost, and performance because one setting can change how code, images, data, identities, or user traffic behave. Review owner, scope, evidence, dependencies, and rollback before production change. Confirm current behavior with logs and metrics before changing settings.

Where you see it

Signals, screens, and Azure surfaces where this term usually becomes operational.

Signal 01

A gallery image version list shows semantic-looking version numbers, target regions, replica counts, storage type, publishing status, and end-of-life metadata. Review owner, scope, evidence, dependencies, and rollback before production change.

Signal 02

VM and scale set deployments reference a specific gallery image version or latest selector, which determines the OS and application baseline. Review owner, scope, evidence, dependencies, and rollback before production change.

Signal 03

Image pipeline logs show source capture, scanning, publishing, replication, and promotion stages before a version becomes available to production deployments. Review owner, scope, evidence, dependencies, and rollback before production change.

When this becomes relevant

Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.

  • Design and document Gallery image version before a production release changes traffic, identity, data access, deployment, image, or runtime behavior.
  • Use Gallery image version during incident triage to narrow the affected scope and gather evidence before changing live settings.
  • Review Gallery image version during architecture, security, cost, performance, and reliability planning for the workload.

Real-world case studies

Different enterprise-style examples that show the term being used to hit measurable objectives.

Case study 01

Gallery image version in action for regional VM rollout

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Fourth Coffee Online needed to roll out a patched web-server image to VM scale sets in two Azure regions.

Business/Technical Objectives
  • Publish a tested image version
  • Replicate before deployment
  • Keep previous version for rollback
  • Track patch adoption by region
Solution Using Gallery image version

The platform team created a Gallery image version from a validated generalized source image. The version was replicated to east and west regions with enough replicas for rollout. VM scale set templates referenced the exact version, not latest, during the first wave. Monitoring tracked boot diagnostics, application health, and patch adoption before the previous image was retired. Architects documented ownership, rollback steps, monitoring signals, and approval evidence so support staff could operate the design without guessing during incidents. The rollout included a lower-environment test, a named business owner, and a short runbook explaining what to verify before and after release. Security, reliability, cost, and performance evidence were captured together so reviewers could see the operational tradeoffs rather than only the deployment result. The team also kept a clear rollback path, including the previous configuration, expected recovery time, and the logs needed to confirm restoration.

Results & Business Impact
  • Patch rollout completed in 36 hours
  • Rollback version remained available for two weeks
  • Deployment failures stayed below 1 percent
  • Regional adoption reporting became automatic
Key Takeaway for Glossary Readers

Gallery image versions make VM baseline changes measurable because every deployment points to a specific published artifact.

Case study 02

Gallery image version in action for university lab refresh

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Northstar Technical College refreshed hundreds of lab VMs before the semester and needed repeatable images.

Business/Technical Objectives
  • Deploy identical lab machines
  • Avoid rebuilding images per campus
  • Retire obsolete versions safely
  • Reduce student login failures
Solution Using Gallery image version

Engineers published a Gallery image version under the approved lab desktop definition. The version included validated course software, security updates, and boot tests. Replication targeted the regions used by campus labs, while the previous version stayed excluded from new deployments but available for rollback. CLI checks confirmed replication state before VM creation began. Architects documented ownership, rollback steps, monitoring signals, and approval evidence so support staff could operate the design without guessing during incidents. The rollout included a lower-environment test, a named business owner, and a short runbook explaining what to verify before and after release. Security, reliability, cost, and performance evidence were captured together so reviewers could see the operational tradeoffs rather than only the deployment result. The team also kept a clear rollback path, including the previous configuration, expected recovery time, and the logs needed to confirm restoration.

Results & Business Impact
  • Lab deployment time dropped by 47 percent
  • Student first-login failures fell by 31 percent
  • Obsolete versions were retired after validation
  • Campuses used the same baseline image
Key Takeaway for Glossary Readers

A gallery image version gives operations a concrete, repeatable source for large VM deployments.

Case study 03

Gallery image version in action for government compliance baseline

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Civic Records Agency needed to prove which hardened server image each case-management VM used.

Business/Technical Objectives
  • Tie every VM to an approved version
  • Preserve vulnerability scan evidence
  • Block unapproved latest drift
  • Enable emergency rollback
Solution Using Gallery image version

The agency used Gallery image version numbers that mapped to security scan reports and approval records. Deployment pipelines required an explicit version ID, and Azure Policy flagged templates using unsupported image sources. Regional replicas were monitored before production rollout. When a patch caused an application issue, operators redeployed the prior version in a test environment and confirmed rollback steps. Architects documented ownership, rollback steps, monitoring signals, and approval evidence so support staff could operate the design without guessing during incidents. The rollout included a lower-environment test, a named business owner, and a short runbook explaining what to verify before and after release. Security, reliability, cost, and performance evidence were captured together so reviewers could see the operational tradeoffs rather than only the deployment result. The team also kept a clear rollback path, including the previous configuration, expected recovery time, and the logs needed to confirm restoration.

Results & Business Impact
  • Image audit traceability reached 100 percent
  • Unapproved image-source findings dropped to zero
  • Emergency rollback test completed in 45 minutes
  • Patch exception review became evidence-based
Key Takeaway for Glossary Readers

Gallery image versions convert VM image compliance from verbal assurance into deployment evidence.

Why use Azure CLI for this?

CLI checks make Gallery image version review repeatable because they capture scoped evidence for configuration, ownership, dependencies, health, and change impact before operators modify production.

CLI use cases

  • List or show the Azure resources related to Gallery image version before selecting a target for deeper review.
  • Capture read-only evidence for Gallery image version during release approval, incident response, access review, or cost investigation.
  • Compare configuration, metrics, logs, and dependent resources for Gallery image version across environments before approving a mutating command.

Before you run CLI

  • Confirm tenant, subscription, resource group, application, plan, gallery, account, image, or deployment scope before trusting command output.
  • Run list and show commands first, then save evidence before create, update, rotate, swap, restart, delete, generalize, or publish changes.
  • Check whether the command affects customer traffic, credentials, images, data access, scaling, storage cost, or compliance evidence.

What output tells you

  • Names, resource IDs, locations, SKUs, enabled states, and parent relationships show whether you are inspecting the intended target.
  • Settings, identities, versions, slots, keys, plans, images, endpoints, or account properties explain how workloads behave today.
  • Timestamps, metrics, usage, health state, and logs help separate Azure configuration issues from application or downstream failures.

Mapped Azure CLI commands

Gallery image version operational checks

direct
az sig show --gallery-name <gallery-name> --resource-group <resource-group>
az sigdiscoverCompute
az sig image-definition list --gallery-name <gallery-name> --resource-group <resource-group>
az sig image-definitiondiscoverCompute
az sig image-definition show --gallery-image-definition <image-definition> --gallery-name <gallery-name> --resource-group <resource-group>
az sig image-definitiondiscoverCompute
az sig image-version list --gallery-image-definition <image-definition> --gallery-name <gallery-name> --resource-group <resource-group>
az sig image-versiondiscoverCompute
az sig image-version show --gallery-image-definition <image-definition> --gallery-image-version <version> --gallery-name <gallery-name> --resource-group <resource-group>
az sig image-versiondiscoverCompute
az sig image-version create --gallery-image-definition <image-definition> --gallery-image-version <version> --gallery-name <gallery-name> --resource-group <resource-group> --target-regions <region>
az sig image-versionprovisionCompute

Architecture context

Technically, Gallery image version is configured or observed through image version number, source image or snapshot, target regions, replica counts, storage account type, exclude-from-latest flag, end-of-life date, sharing, and deployment references. Important settings include version name, source resource ID, publishing profile, regional replicas, storage type, latest version behavior, encryption, replication mode, end-of-life date, and target region availability. Operators inspect it with az sig image-version output, replication state, VM source references, build pipeline logs, vulnerability scan evidence, deployment history, Activity Log entries, and gallery replication metrics.

Security

Security for Gallery image version starts with approved source image, scanning results, encryption, gallery RBAC, sharing scope, version retirement, security feature compatibility, and prevention of unapproved latest-version drift. Review who can create, update, list, rotate, swap, publish, replicate, read diagnostics, or use the resource. Prefer Microsoft Entra ID, managed identity, least privilege, private networking, secure transfer, and audited automation where the service supports them. Keep secrets out of code and avoid public exposure unless a documented exception exists. Capture role assignments, Activity Log entries, diagnostic settings, policy decisions, and owner approvals so access and data handling are intentional. Review owner, scope, evidence, dependencies, and rollback before production change.

Cost

Cost for Gallery image version is driven by regional replicas, storage type, retained old versions, failed VM deployments, duplicate image builds, long-lived test versions, and unnecessary replication to unused regions. The expensive mistake is not only Azure consumption; it can also be failed releases, duplicate environments, over-retained images, unnecessary diagnostic volume, idle premium capacity, emergency support, or cleanup after weak design evidence. Review whether the workload truly needs the selected tier, replicas, runtime plan, retention, redundancy, access tier, monitoring, or automation pattern. Use tags, budgets, alerts, and cleanup reviews so teams can explain why the design exists. Review owner, scope, evidence, dependencies, and rollback before production change.

Reliability

Reliability for Gallery image version depends on replication completion, regional availability, source image health, version rollback, deployment compatibility, end-of-life handling, and avoiding accidental deletion of active versions. A resource can exist and still fail the business workflow if versioning, slot state, runtime support, trigger health, image replication, storage redundancy, network rules, or downstream services are wrong. Test failure modes, deployment behavior, rollback steps, monitoring signals, and maintenance windows before relying on the design. During incidents, compare logs, metrics, configuration, deployment history, and application traces from the same time window before changing production. Review owner, scope, evidence, dependencies, and rollback before production change.

Performance

Performance for Gallery image version depends on replica location, image size, disk type, VM boot time, replication lag, region selection, version availability, guest agent readiness, and deployment fan-out during scale events. Measure platform metrics and workload completion times because a healthy control-plane response does not prove users received the right result. Test with realistic regions, data sizes, package sizes, image replication, trigger load, identity paths, network routes, cache state, and downstream limits. When performance regresses, compare configuration changes, resource limits, client logs, diagnostic data, and workload timing before adding capacity or blaming one service. Review owner, scope, evidence, dependencies, and rollback before production change.

Operations

Operations for Gallery image version require version naming, promotion workflow, release notes, replica monitoring, retirement process, deployment references, VM impact analysis, and runbooks for reverting to a previous version. Before a change, capture read-only CLI output, portal evidence when useful, owner tags, dependency lists, expected behavior, and rollback steps. During incidents, avoid changing several settings at once; compare metrics, logs, deployment operations, identity evidence, network state, and downstream health first. Keep runbooks clear enough for support teams to verify current behavior quickly. Good operations make the term observable, reviewable, and recoverable during releases, audits, and incidents. Review owner, scope, evidence, dependencies, and rollback before production change.

Common mistakes

  • Treating Gallery image version as a simple label instead of checking live scope, owner, dependencies, and current configuration.
  • Running a mutating command for Gallery image version in the wrong subscription, resource group, app, gallery, image, or storage account context.
  • Assuming successful deployment proves Gallery image version works without checking logs, metrics, user behavior, and rollback evidence.