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.