[Compute] Add Azure Compute Gallery soft-delete policy, recycle-bin, and bypass-delete support

[anuraganand202]

Preconditions

• No need to upgrade the Python SDK. The az sig commands are AAZ-generated and the required REST API specifications are ready.

Related command

# Configure soft delete when creating a gallery
az sig create \
  --resource-group MyResourceGroup \
  --gallery-name MyGallery \
  --location westus \
  --soft-delete true \
  --soft-delete-retention-period 30 \
  --soft-delete-grace-period 7

# Update the soft-delete policy (use --soft-delete false to disable it)
az sig update \
  --resource-group MyResourceGroup \
  --gallery-name MyGallery \
  --soft-delete true \
  --soft-delete-retention-period 30 \
  --soft-delete-grace-period 7

# List soft-deleted image versions for an image definition
az sig image-version list-soft-deleted \
  --resource-group MyResourceGroup \
  --gallery-name MyGallery \
  --gallery-image-definition MyImage

# Permanently delete an image version without placing it in the recycle bin
az sig image-version delete \
  --resource-group MyResourceGroup \
  --gallery-name MyGallery \
  --gallery-image-definition MyImage \
  --gallery-image-version 1.0.0 \
  --bypass-soft-delete

Resource Provider

Microsoft.Compute

Description of Feature or Work Requested

Add complete Azure Compute Gallery image-version soft-delete support to Azure CLI, corresponding to the PowerShell design in https://github.com/Azure/azure-powershell-cmdlet-review-pr/issues/1575.

1. Gallery soft-delete policy

The existing az sig create and az sig update commands already expose --soft-delete, which maps to properties.softDeletePolicy.isSoftDeleteEnabled. That property is available before API version 2026-03-03 and remains available in 2026-03-03.

Keep the existing option and add the following CLI-style, kebab-case options:

• --soft-delete-retention-period: maps to properties.softDeletePolicy.retentionPeriodInDays; added in API version 2026-03-03. The value is specified in days.
• --soft-delete-grace-period: maps to properties.softDeletePolicy.gracePeriodInDays; added in API version 2026-03-03. The value is specified in days.

Both values are nullable integers. az sig update --soft-delete false should remain the way to disable soft delete; separate enable/disable commands are not requested. Gallery create/update must use API version 2026-03-03 or later when either new period option is supplied.

2. Recycle-bin listing

Add az sig image-version list-soft-deleted to call SoftDeletedResource_ListByArtifactName with artifact type Images for the specified gallery image definition.

The operation itself is available from API version 2024-03-03. Its existing response fields include:

• properties.resourceArmId
• properties.softDeletedTime
• properties.softDeletedArtifactType

API version 2026-03-03 adds these response fields:

• properties.consumptionEndTime
• properties.hardDeletionTargetTime

The generated CLI command should use API version 2026-03-03 or later so it returns the complete requested response model. It should return a list so standard Azure CLI JMESPath --query can select a particular image version when needed.

The existing preview command az sig image-version undelete remains the recovery command for a soft-deleted image version.

3. Bypass soft delete during deletion

Add the boolean switch --bypass-soft-delete to az sig image-version delete and serialize it as the query parameter bypassSoftDelete=true.

Behavior:

• When omitted, preserve the current policy-driven delete behavior: soft delete when the gallery policy is enabled and permanent delete when it is disabled.
• When specified, permanently hard-delete the image version instead of placing it in the recycle bin.
• The help text should clearly warn that this operation is irreversible.

The bypassSoftDelete query parameter is supported from API version 2026-03-03.

4. Shared and community image-version response fields

Update the generated output schemas for these commands where applicable:

• az sig image-version show-shared
• az sig image-version list-shared
• az sig image-version show-community
• az sig image-version list-community

API version 2026-03-03 adds the following properties to shared and community image-version responses:

• properties.consumptionEndTime
• properties.imageState

imageState is an extensible value with currently defined values Active and SoftDeleted. consumptionEndTime is nullable and is absent for active image versions.

Compatibility and tests

• Existing command behavior must remain unchanged when the new options are omitted.
• Add command tests for gallery create/update policy serialization, listing soft-deleted versions, normal deletion, bypass deletion, and the new shared/community response fields.
• Verify --bypass-soft-delete uses API version 2026-03-03 and sends bypassSoftDelete=true; omitting it must omit the query parameter or send false.
• Verify the recycle-bin command invokes SoftDeletedResource_ListByArtifactName with artifact type Images and API version 2026-03-03.
• Verify active shared/community versions tolerate an omitted consumptionEndTime and unknown future imageState values do not fail deserialization.
• Since these commands are AAZ-generated, regenerate them from the updated Compute REST API specifications rather than adding a separate handwritten SDK path where generation is supported.

API-version support

Surface	API-version support
properties.softDeletePolicy.isSoftDeleteEnabled / existing --soft-delete	Available before 2026-03-03 and retained in 2026-03-03
properties.softDeletePolicy.retentionPeriodInDays	Added in 2026-03-03
properties.softDeletePolicy.gracePeriodInDays	Added in 2026-03-03
SoftDeletedResource_ListByArtifactName operation	Available from 2024-03-03
Recycle-bin properties.consumptionEndTime	Added in 2026-03-03
Recycle-bin properties.hardDeletionTargetTime	Added in 2026-03-03
Shared/community properties.consumptionEndTime and properties.imageState	Added in 2026-03-03
DELETE query parameter bypassSoftDelete	Supported from 2026-03-03

Minimum API Version Required

• 2024-03-03 is sufficient for the existing SoftDeletedResource_ListByArtifactName operation and its original response model.
• 2026-03-03 is required for retention/grace-period configuration, the complete recycle-bin response model, the new shared/community response properties, and bypassSoftDelete.

Therefore, the complete proposed CLI surface should be generated using API version 2026-03-03 or later.

Swagger PR link / SDK link

• Gallery soft-delete retention and grace periods: Add retentionPeriodInDays and gracePeriodInDays to SoftDeletePolicy (2026-03-03) azure-rest-api-specs#44214
• Soft-deleted and shared/community response fields: Add SIG soft-delete GET/LIST fields for gallery image versions (2026-03-03) azure-rest-api-specs#44434
• bypassSoftDelete query parameter: Add bypass soft delete query parameter azure-rest-api-specs#46100
• Corresponding PowerShell design review: https://github.com/Azure/azure-powershell-cmdlet-review-pr/issues/1575

Request Example

Gallery create/update request body (2026-03-03 or later for the period properties):

{
  "location": "westus",
  "properties": {
    "softDeletePolicy": {
      "isSoftDeleteEnabled": true,
      "retentionPeriodInDays": 30,
      "gracePeriodInDays": 7
    }
  }
}

Permanent image-version deletion using API version 2026-03-03:

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/galleries/{galleryName}/images/{galleryImageName}/versions/{galleryImageVersionName}?api-version=2026-03-03&bypassSoftDelete=true

Example recycle-bin response item using API version 2026-03-03:

{
  "properties": {
    "resourceArmId": "/subscriptions/{subscriptionId}/resourceGroups/MyResourceGroup/providers/Microsoft.Compute/galleries/MyGallery/images/MyImage/versions/1.0.0",
    "softDeletedTime": "2026-09-01T00:00:00Z",
    "softDeletedArtifactType": "Images",
    "consumptionEndTime": "2026-09-08T00:00:00Z",
    "hardDeletionTargetTime": "2026-10-01T00:00:00Z"
  }
}

Example shared/community image-version properties using API version 2026-03-03:

{
  "properties": {
    "consumptionEndTime": "2026-09-08T00:00:00Z",
    "imageState": "SoftDeleted"
  }
}

Target Date

2026-09-20

PM Contact

saraic

Engineer Contact

anuraganand

Additional context

This follows the format and command-naming pattern used by the completed Gallery Image Version CLI request #30820.

[yonzhan]

Thank you for opening this issue, we will look into it.