Edit

Set-AzSnapshotImmutabilityPolicy

Sets or updates the time-bound deletion protection policy for a managed disk snapshot.

Syntax

DefaultParameterSet (Default)

Set-AzSnapshotImmutabilityPolicy
    [-Name] <String>
    -PolicyType <String>
    -DurationInDays <Int32>
    -ResourceGroupName <String>
    [-Force]
    [-AsJob]
    [-DefaultProfile <IAzureContextContainer>]
    [-WhatIf]
    [-Confirm]
    [-AcquirePolicyToken]
    [-ChangeReference <String>]
    [<CommonParameters>]

ResourceIdParameterSet

Set-AzSnapshotImmutabilityPolicy
    [-ResourceId] <String>
    -PolicyType <String>
    -DurationInDays <Int32>
    [-Force]
    [-AsJob]
    [-DefaultProfile <IAzureContextContainer>]
    [-WhatIf]
    [-Confirm]
    [-AcquirePolicyToken]
    [-ChangeReference <String>]
    [<CommonParameters>]

InputObjectParameterSet

Set-AzSnapshotImmutabilityPolicy
    [-InputObject] <PSSnapshot>
    -PolicyType <String>
    -DurationInDays <Int32>
    [-Force]
    [-AsJob]
    [-DefaultProfile <IAzureContextContainer>]
    [-WhatIf]
    [-Confirm]
    [-AcquirePolicyToken]
    [-ChangeReference <String>]
    [<CommonParameters>]

Description

The Set-AzSnapshotImmutabilityPolicy cmdlet applies or updates deletion protection on an existing managed disk snapshot. Unlocked policies can be shortened or extended. Active Locked policies can only be extended; they cannot be removed or changed to Unlocked.

Duration is total retention from the service-assigned start, not additional days from now. Active-policy updates, including changing Unlocked to Locked, retain that start. Replacing an expired policy creates a new start. Reducing an Unlocked policy's duration, including when locking it, can immediately expire protection.

Unlocked updates require Microsoft.Compute/snapshots/updateImmutabilityPolicy/action; Locked updates require Microsoft.Compute/snapshots/updateImmutabilityPolicyLock/action. Both require snapshot read permission. Every Locked update requires acknowledgement because applying or extending Locked retention cannot be undone before expiry.

The cmdlet returns the snapshot after verifying the persisted policy. If verification fails, the change may already have applied. Inspect the snapshot's ImmutabilityPolicy with Get-AzSnapshot before retrying.

Examples

Example 1: Apply an Unlocked policy by name

$snapshot = Set-AzSnapshotImmutabilityPolicy -ResourceGroupName "rg-backup" -Name "snapshot-01" -PolicyType Unlocked -DurationInDays 7
$snapshot.ImmutabilityPolicy | Format-List

This command applies a seven-day Unlocked policy and displays it.

Example 2: Apply a policy by resource ID

Set-AzSnapshotImmutabilityPolicy -ResourceId "/subscriptions/<subscription-id>/resourceGroups/rg-backup/providers/Microsoft.Compute/snapshots/snapshot-01" -PolicyType Unlocked -DurationInDays 7

This command applies the policy to the snapshot identified by its resource ID.

Example 3: Change a policy by piping a snapshot

Get-AzSnapshot -ResourceGroupName "rg-backup" -SnapshotName "snapshot-01" |
    Set-AzSnapshotImmutabilityPolicy -PolicyType Unlocked -DurationInDays 14

This command sets Unlocked retention to 14 days without resetting its start.

Example 4: Shorten the total Unlocked duration

$snapshot = Get-AzSnapshot -ResourceGroupName "rg-backup" -SnapshotName "snapshot-01"
$snapshot = Set-AzSnapshotImmutabilityPolicy -InputObject $snapshot -PolicyType Unlocked -DurationInDays 7
$snapshot.ImmutabilityPolicy |
    Format-List Type, ImmutabilityDurationDays, PolicyStartTime, PolicyExpirationTime, IsPolicyExpired

This example shortens an active 14-day Unlocked policy to seven days from its original start. If seven days have elapsed, protection expires.

Example 5: Preview locking a policy

Get-AzSnapshot -ResourceGroupName "rg-backup" -SnapshotName "snapshot-01" |
    Set-AzSnapshotImmutabilityPolicy -PolicyType Locked -DurationInDays 14 -WhatIf

This command previews a Locked policy without changing the snapshot. Locking an active Unlocked policy retains its original start; the requested duration is measured from that start.

Example 6: Run an Unlocked update as a job

$job = Set-AzSnapshotImmutabilityPolicy -ResourceGroupName "rg-backup" -SnapshotName "snapshot-01" -PolicyType Unlocked -DurationInDays 7 -AsJob
$snapshot = $job | Wait-Job | Receive-Job -ErrorAction Stop
$snapshot.ImmutabilityPolicy | Format-List

This example retrieves the updated snapshot from a background job.

Parameters

-AcquirePolicyToken

Acquire an Azure Policy token automatically for this resource operation.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-AsJob

Runs the cmdlet in the background and returns a job.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ChangeReference

The change reference resource ID for this resource operation.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Confirm

Prompts you for confirmation before running the cmdlet.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False
Aliases:cf

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-DefaultProfile

The credentials, account, tenant, and subscription used for communication with Azure.

Parameter properties

Type:IAzureContextContainer
Default value:None
Supports wildcards:False
DontShow:False
Aliases:AzContext, AzureRmContext, AzureCredential

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-DurationInDays

Specifies total retention in days. The value must be positive; the service validates the maximum supported duration.

Parameter properties

Type:Int32
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Force

Suppresses the additional Locked-retention acknowledgement, but not standard confirmation, permissions, or retention restrictions. -Confirm:$false alone does not suppress this acknowledgement.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-InputObject

Specifies the snapshot whose policy is updated. Only its resource ID is used; current policy is read from Azure.

Parameter properties

Type:PSSnapshot
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

InputObjectParameterSet
Position:0
Mandatory:True
Value from pipeline:True
Value from pipeline by property name:False
Value from remaining arguments:False

-Name

Specifies the snapshot name.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:SnapshotName

Parameter sets

DefaultParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-PolicyType

Specifies the policy type: Unlocked or Locked.

Parameter properties

Type:String
Default value:None
Accepted values:Unlocked, Locked
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ResourceGroupName

Specifies the snapshot's resource group.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

DefaultParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ResourceId

Specifies the snapshot resource ID in the current subscription.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:Id

Parameter sets

ResourceIdParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False
Aliases:wi

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

PSSnapshot

Outputs

PSSnapshot

Notes

Apply policies after snapshot creation. Copies do not inherit protection. Snapshots in Pending, Unknown, or InstantAccess states cannot be updated.

Acknowledgement occurs before a background job starts. Cancelling a job does not guarantee server cancellation or rollback.