Configure immutability policies for blob versions

To enable support for version-level immutability when you create a storage account in the Azure portal, follow these steps:

1. Navigate to the Storage accounts page in the Azure portal.

2. Select the Create button to create a new account.

3. Fill out the Basics tab.

4. On the Data protection tab, under Access control, select Enable version-level immutability support. When you check this box, the box for Enable versioning for blobs is also automatically checked.

5. Select Review + Create to validate your account parameters and create the storage account.

   

After the storage account is created, you can configure a default version-level policy for the account. For more information, see Configure a default time-based retention policy.

N/A

To enable support for version-level immutability when you create a storage account with Azure CLI, call the az storage account create command with the --enable-alw parameter specified. You can optionally specify a default policy for the storage account at the same time, as shown in the following example. Remember to replace placeholders in angle brackets with your own values:

az storage account create \
    --name <storage-account> \
    --resource-group <resource-group> \
    --enable-alw \
    --immutability-period-in-days 90 \
    --immutability-state unlocked \
    --allow-protected-append-writes true

To create a container that supports version-level immutability in the Azure portal, follow these steps:

1. Navigate to the Containers page for your storage account in the Azure portal, and select Add.

2. In the New container dialog, provide a name for your container, then expand the Advanced section.

3. Select Enable version-level immutability support to enable version-level immutability for the container.

   

To create a container that supports version-level immutability with PowerShell, first install the Az.Storage module, version 3.12.0 or later.

Next, call the New-AzRmStorageContainer command with the -EnableImmutableStorageWithVersioning parameter, as shown in the following example. Remember to replace placeholders in angle brackets with your own values:

# Create a container with version-level immutability support.
$container = New-AzRmStorageContainer -ResourceGroupName <resource-group> `
    -StorageAccountName <storage-account> `
    -Name <container> `
    -EnableImmutableStorageWithVersioning

# Verify that version-level immutability support is enabled for the container
$container.ImmutableStorageWithVersioning

To create a container that supports version-level immutability with Azure CLI, first install Azure CLI version 2.27 or later. For more information about installing Azure CLI, see How to install the Azure CLI.

Next, call the az storage container-rm create command, specifying the --enable-vlw parameter. Remember to replace placeholders in angle brackets with your own values:

# Create a container with version-level immutability support.
az storage container-rm create \
    --name <container> \
    --storage-account <storage-account> \
    --resource-group <resource-group> \
    --enable-vlw

# Verify that version-level immutability support is enabled for the container
az storage container-rm show \
    --storage-account <storage-account> \
    --name <container> \
    --query '[immutableStorageWithVersioning.enabled]' \
    --output tsv

To migrate a container to support version-level immutability policies in the Azure portal, follow these steps:

1. Navigate to the desired container.

2. In the context menu of the container, then select Access policy.

3. Under Immutable blob storage, select Add policy.

4. For the Policy type field, choose Time-based retention, and specify the retention interval.

5. Select Enable version-level immutability.

6. Select OK to create a container-level policy with the specified retention interval and then begin the migration to version-level immutability support.

   

While the migration operation is underway, the scope of the policy on the container shows as Container. Any operations related to managing version-level immutability policies aren't permitted while the container migration is in progress. Other operations on blob data will proceed normally during migration.

After the migration is complete, the scope of the policy on the container shows as Version. The policy shown is a default policy on the container that automatically applies to all blob versions subsequently created in the container. The default policy can be overridden on any version by specifying a custom policy for that version.

To migrate a container to support version-level immutable storage with PowerShell, first make sure that a container-level time-based retention policy exists for the container. To create one, call Set-AzRmStorageContainerImmutabilityPolicy.

Set-AzRmStorageContainerImmutabilityPolicy -ResourceGroupName <resource-group> `
   -StorageAccountName <storage-account> `
   -ContainerName <container> `
   -ImmutabilityPeriod <retention-interval-in-days>

Next, call the Invoke-AzRmStorageContainerImmutableStorageWithVersioningMigration command to migrate the container. Include the -AsJob parameter to run the command asynchronously. Running the operation asynchronously is recommended, as the migration may take some time to complete.

$migrationOperation = Invoke-AzRmStorageContainerImmutableStorageWithVersioningMigration `
    -ResourceGroupName <resource-group> `
    -StorageAccountName <storage-account> `
    -Name <container> `
    -AsJob

To check the status of the long-running operation, read the operation's JobStateInfo.State property.

$migrationOperation.JobStateInfo.State

If the container doesn't have an existing time-based retention policy when you attempt to migrate to version-level immutability, then the operation fails. The following example checks the value of the JobStateInfo.State property and displays the error message if the operation failed because the container-level policy doesn't exist.

if ($migrationOperation.JobStateInfo.State -eq "Failed") {
Write-Host $migrationOperation.Error
}
The container <container-name> must have an immutability policy set as a default policy
before initiating container migration to support object level immutability with versioning.

After the migration is complete, check the Output property of the operation to see that support for version-level immutability is enabled.

$migrationOperation.Output

For more information about PowerShell jobs, see Run Azure PowerShell cmdlets in PowerShell Jobs.

To migrate a container to support version-level immutable storage with Azure CLI, first make sure that a container-level time-based retention policy exists for the container. To create one, call az storage container immutability-policy create.

az storage container immutability-policy create \
    --resource-group <resource-group> \
    --account-name <storage-account> \
    --container-name <container> \
    --period <retention-interval-in-days>

Next, call the az storage container-rm migrate-vlw command to migrate the container. Include the --no-wait parameter to run the command asynchronously. Running the operation asynchronously is recommended, as the migration may take some time to complete.

az storage container-rm migrate-vlw \
    --resource-group <resource-group> \
    --storage-account <storage-account> \
    --name <container> \
    --no-wait

To check the status of the long-running operation, read the value of the migrationState property.

az storage container-rm show \
    --storage-account <storage-account> \
    --name <container> \
    --query '[immutableStorageWithVersioning.migrationState]' \
    --output tsv

To configure a default version-level immutability policy for a storage account in the Azure portal, follow these steps:

1. In the Azure portal, navigate to your storage account.

2. Under Data management, select Data protection.

3. On the Data protection page, locate the Access control section. If the storage account was created with support for version-level immutability, then the Manage policy button appears in the Access control section.

   

4. Select the Manage policy button to display the Manage version-level immutability policy dialog.

5. Add a default time-based retention policy for the storage account.

   

To configure a default version-level immutability policy for a container in the Azure portal, follow these steps:

1. In the Azure portal, navigate to the Containers page, and locate the container to which you want to apply the policy.

2. In the context menu of the container, and choose Access policy.

3. In the Access policy dialog, under the Immutable blob storage section, choose Add policy.

4. Select Time-based retention policy and specify the retention interval.

5. Choose whether to allow protected append writes.

   The Append blobs option enables your workloads to add new blocks of data to the end of an append blob by using the Append Block operation.

   The Block and append blobs option extends this support by adding the ability to write new blocks to a block blob. The Blob Storage API does not provide a way for applications to do this directly. However, applications can accomplish this by using append and flush methods that are available in the Data Lake Storage API. Also, this property enables Microsoft applications such as Azure Data Factory to append blocks of data by using internal APIs. If your workloads depend on any of these tools, then you can use this property to avoid errors that can appear when those tools attempt to append data to blobs.

   To learn more about these options, see Allow protected append blobs writes.

   

To configure a default version-level immutability policy for a container with PowerShell, call the Set-AzRmStorageContainerImmutabilityPolicy command.

Set-AzRmStorageContainerImmutabilityPolicy -ResourceGroupName <resource-group> `
   -StorageAccountName <storage-account> `
   -ContainerName <container> `
   -ImmutabilityPeriod <retention-interval-in-days> `
   -AllowProtectedAppendWrite $true

To configure a default version-level immutability policy for a container with Azure CLI, call the az storage container immutability-policy create command.

az storage container immutability-policy create \
    --account-name <storage-account> \
    --container-name <container> \
    --period <retention-interval-in-days> \
    --allow-protected-append-writes true

The Azure portal displays a list of blobs when you navigate to a container. Each blob displayed represents the current version of the blob. You can access a list of previous versions by opening the context menu of the blob and then choosing View previous versions.

Configure a retention policy on the current version of a blob

To configure a time-based retention policy on the current version of a blob, follow these steps:

1. Navigate to the container that contains the target blob.

2. In the context menu of the blob, and choose Access policy. If a time-based retention policy has already been configured for the previous version, it appears in the Access policy dialog.

3. In the Access policy dialog, under the Immutable blob versions section, choose Add policy.

4. Select Time-based retention policy and specify the retention interval.

5. Select OK to apply the policy to the current version of the blob.

   

You can view the properties for a blob to see whether a policy is enabled on the current version. Select the blob, then navigate to the Overview tab and locate the Version-level immutability policy property. If a policy is enabled, the Retention period property will display the expiry date and time for the policy. Keep in mind that a policy may either be configured for the current version, or may be inherited from the blob's parent container if a default policy is in effect.

Configure a retention policy on a previous version of a blob

You can also configure a time-based retention policy on a previous version of a blob. A previous version is always immutable in that it can't be modified. However, a previous version can be deleted. A time-based retention policy protects against deletion while it is in effect.

To configure a time-based retention policy on a previous version of a blob, follow these steps:

1. Navigate to the container that contains the target blob.

2. Select the blob, then navigate to the Versions tab.

3. Locate the target version, then, in the context menu of the version, choose Access policy. If a time-based retention policy has already been configured for the previous version, it appears in the Access policy dialog.

4. In the Access policy dialog, under the Immutable blob versions section, choose Add policy.

5. Select Time-based retention policy and specify the retention interval.

6. Select OK to apply the policy to the current version of the blob.

   

To configure a time-based retention policy on a blob version with PowerShell, call the Set-AzStorageBlobImmutabilityPolicy command.

The following example shows how to configure an unlocked policy on the current version of a blob. Remember to replace placeholders in angle brackets with your own values:

# Get the storage account context
$ctx = (Get-AzStorageAccount `
        -ResourceGroupName <resource-group> `
        -Name <storage-account>).Context

Set-AzStorageBlobImmutabilityPolicy -Container <container> `
    -Blob <blob-version> `
    -Context $ctx `
    -ExpiresOn "2021-09-01T12:00:00Z" `
    -PolicyMode Unlocked

To configure a time-based retention policy on a blob version with Azure CLI, first install the Azure CLI, version 2.29.0 or later.

Next, call the az storage blob immutability-policy set command to configure the time-based retention policy. The following example shows how to configure an unlocked policy on the current version of a blob. Remember to replace placeholders in angle brackets with your own values:

az storage blob immutability-policy set \
    --expiry-time 2021-09-20T08:00:00Z \
    --policy-mode Unlocked \
    --container <container> \
    --name <blob-version> \
    --account-name <storage-account> \
    --auth-mode login

To modify an unlocked time-based retention policy in the Azure portal, follow these steps:

1. Locate the target container or version. In the context menu of the container or version, choose Access policy.

2. Locate the existing unlocked immutability policy. In the context menu, select Edit from the menu.

   

3. Provide the new date and time for the policy expiration.

To delete the unlocked policy, select Delete from the context menu.

To modify an unlocked time-based retention policy with PowerShell, call the Set-AzStorageBlobImmutabilityPolicy command on the blob version with the new date and time for the policy expiration. Remember to replace placeholders in angle brackets with your own values:

$containerName = "<container>"
$blobName = "<blob>"

# Get the previous blob version.
$blobVersion = Get-AzStorageBlob -Container $containerName `
    -Blob $blobName `
    -VersionId "2021-08-31T00:26:41.2273852Z" `
    -Context $ctx

# Extend the retention interval by five days.
$blobVersion = $blobVersion |
    Set-AzStorageBlobImmutabilityPolicy -ExpiresOn (Get-Date).AddDays(5) `

# View the new policy parameters.
$blobVersion.BlobProperties.ImmutabilityPolicy

To delete an unlocked retention policy, call the Remove-AzStorageBlobImmutabilityPolicy command.

$blobVersion = $blobVersion | Remove-AzStorageBlobImmutabilityPolicy

To modify an unlocked time-based retention policy with PowerShell, call the az storage blob immutability-policy set command on the blob version with the new date and time for the policy expiration. Remember to replace placeholders in angle brackets with your own values:

az storage blob immutability-policy set \
    --expiry-time 2021-10-0T18:00:00Z \
    --policy-mode Unlocked \
    --container <container> \
    --name <blob-version> \
    --account-name <storage-account> \
    --auth-mode login

To delete an unlocked retention policy, call the az storage blob immutability-policy delete command.

az storage blob immutability-policy delete \
    --container <container> \
    --name <blob-version> \
    --account-name <storage-account> \
    --auth-mode login

To lock a policy in the Azure portal, follow these steps:

1. Locate the target container or version. In the context menu of the container or version, choose Access policy.

2. Under the Immutable blob versions section, locate the existing unlocked policy. Select Lock policy from the context menu.

3. Confirm that you want to lock the policy.

   

To lock a policy with PowerShell, call the Set-AzStorageBlobImmutabilityPolicy command and set the PolicyMode parameter to Locked.

The following example shows how to lock a policy by specifying the same retention interval that was in effect for the unlocked policy. You can also change the expiry at the time that you lock the policy.

# Get the previous blob version.
$blobVersion = Get-AzStorageBlob -Container $containerName `
    -Blob $blobName `
    -VersionId "2021-08-31T00:26:41.2273852Z" `
    -Context $ctx

$blobVersion = $blobVersion |
    Set-AzStorageBlobImmutabilityPolicy `
        -ExpiresOn $blobVersion.BlobProperties.ImmutabilityPolicy.ExpiresOn `
        -PolicyMode Locked

To lock a policy with PowerShell, call the az storage blob immutability-policy set command and set the --policy-mode parameter to Locked. You can also change the expiry at the time that you lock the policy.

az storage blob immutability-policy set \
    --expiry-time 2021-10-0T18:00:00Z \
    --policy-mode Locked \
    --container <container> \
    --name <blob-version> \
    --account-name <storage-account> \
    --auth-mode login

To configure a legal hold on a blob version with the Azure portal, follow these steps:

1. Locate the target version, which may be the current version or a previous version of a blob. In the context menu of the target version, choose Access policy.

2. Under the Immutable blob versions section, select Add policy.

3. Choose Legal hold as the policy type, and select OK to apply it.

The following image shows a current version of a blob with both a time-based retention policy and legal hold configured.

To clear a legal hold, navigate to the Access policy dialog, in the context menu, choose Delete.

To configure or clear a legal hold on a blob version with PowerShell, call the Set-AzStorageBlobLegalHold command.

# Set a legal hold
Set-AzStorageBlobLegalHold -Container <container> `
    -Blob <blob-version> `
    -Context $ctx `
    -EnableLegalHold

# Clear a legal hold
Set-AzStorageBlobLegalHold -Container <container> `
    -Blob <blob-version> `
    -Context $ctx `
    -DisableLegalHold

To configure or clear a legal hold on a blob version with Azure CLI, call the az storage blob set-legal-hold command.

# Set a legal hold
az storage blob set-legal-hold \
    --legal-hold \
    --container <container> \
    --name <blob-version> \
    --account-name <account-name> \
    --auth-mode login

# Clear a legal hold
az storage blob set-legal-hold \
    --legal-hold false \
    --container <container> \
    --name <blob-version> \
    --account-name <account-name> \
    --auth-mode login