Configure immutability policies for blob versions

Immutable storage for Azure Blob Storage enables users to store business-critical data in a WORM (Write Once, Read Many) state. While in a WORM state, data can't be modified or deleted for a user-specified interval. By configuring immutability policies for blob data, you can protect your data from overwrites and deletes. Immutability policies include time-based retention policies and legal holds. For more information about immutability policies for Blob Storage, see Store business-critical blob data with immutable storage.

An immutability policy may be scoped either to an individual blob version or to a container. This article describes how to configure a version-level immutability policy. To learn how to configure container-level immutability policies, see Configure immutability policies for containers.

Note

Immutability policies are not supported in accounts that have the Network File System (NFS) 3.0 protocol or the SSH File Transfer Protocol (SFTP) enabled on them.

Configuring a version-level immutability policy is a two-step process:

  1. First, enable support for version-level immutability on a new storage account or on a new or existing container. See Enable support for version-level immutability for details.
  2. Next, configure a time-based retention policy or legal hold that applies to one or more blob versions in that container.

Prerequisites

To configure version-level time-based retention policies, blob versioning must be enabled for the storage account. Keep in mind that enabling blob versioning may have a billing impact. To learn how to enable blob versioning, see Enable and manage blob versioning.

For information about supported storage account configurations for version-level immutability policies, see Supported account configurations.

Enable support for version-level immutability

Before you can apply a time-based retention policy to a blob version, you must enable support for version-level immutability. You can enable support for version-level immutability on a new storage account, or on a new or existing container.

Enable version-level immutability support on a storage account

You can enable support for version-level immutability only when you create a new storage account.

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.

    Screenshot showing how to create a storage account with version-level immutability support

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.

If version-level immutability support is enabled for the storage account and the account contains one or more containers, then you must delete all containers before you delete the storage account, even if there are no immutability policies in effect for the account or containers.

Note

Version-level immutability cannot be disabled after it is enabled on the storage account, although locked policies can be deleted.

Enable version-level immutability support on a container

Both new and existing containers can be configured to support version-level immutability. However, an existing container must undergo a migration process in order to enable support.

Keep in mind that enabling version-level immutability support for a container doesn't make data in that container immutable. You must also either configure a default immutability policy for the container, or an immutability policy on a specific blob version. If you enabled version-level immutability for the storage account when it was created, you can also configure a default immutability policy for the account.

Enable version-level immutability for a new container

To use a version-level immutability policy, you must first explicitly enable support for version-level WORM on the container. You can enable support for version-level WORM either when you create the container, or when you add a version-level immutability policy to an existing container.

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.

    Screenshot showing how to create a container with version-level immutability enabled

If version-level immutability support is enabled for a container and the container contains one or more blobs, then you must delete all blobs in the container before you can delete the container, even if there are no immutability policies in effect for the container or its blobs.

Migrate an existing container to support version-level immutability

To configure version-level immutability policies for an existing container, you must migrate the container to support version-level immutable storage. Container migration may take some time and can't be reversed. You can migrate 10 containers at a time per storage account.

To migrate an existing container to support version-level immutability policies, the container must have a container-level time-based retention policy configured. The migration fails unless the container has an existing policy. The retention interval for the container-level policy is maintained as the retention interval for the default version-level policy on the container.

If the container has an existing container-level legal hold, then it can't be migrated until the legal hold is removed.

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.

    Screenshot showing how to migrate an existing container to support version-level immutability

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.

Screenshot showing container migration in process

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.

Screenshot showing completed container migration

Configure a default time-based retention policy

After you have enabled version-level immutability support for a storage account or for an individual container, you can specify a default version-level time-based retention policy for the account or container. When you specify a default policy for an account or container, that policy applies by default to all new blob versions that are created in the account or container. You can override the default policy for any individual blob version in the account or container.

The default policy isn't automatically applied to blob versions that existed before the default policy was configured.

If you migrated an existing container to support version-level immutability, then the container-level policy that was in effect before the migration is migrated to a default version-level policy for the container.

To configure a default version-level immutability policy for a storage account or container, use the Azure portal, PowerShell, Azure CLI, or one of the Azure Storage SDKs. Make sure that you have enabled support for version-level immutability for the storage account or container, as described in Enable support for version-level immutability.

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.

    Screenshot showing how to manage the default version-level immutability policy for a storage account

  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.

    Screenshot showing how to configure a default version-level retention policy for a 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 Gen2 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.

    Screenshot showing how to configure immutability policy scoped to container.

Determine the scope of a retention policy on a container

To determine the scope of a time-based retention policy 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, locate the Scope field. If the container is configured with a default version-level retention policy, then the scope is set to Version, as shown in the following image:

    Screenshot showing default version-level retention policy configured for container

  4. If the container is configured with a container-level retention policy, then the scope is set to Container, as shown in the following image:

    Screenshot showing container-level retention policy configured for container

Configure a time-based retention policy on an existing version

Time-based retention policies maintain blob data in a WORM state for a specified interval. For more information about time-based retention policies, see Time-based retention policies for immutable blob data.

You have three options for configuring a time-based retention policy for a blob version:

  • Option 1: You can configure a default policy on the storage account or container that applies to all objects in the account or container. Objects in the account or container will inherit the default policy unless you explicitly override it by configuring a policy on an individual blob version. For more information, see Configure a default time-based retention policy.
  • Option 2: You can configure a policy on the current version of the blob. This policy can override a default policy configured on the storage account or container, if a default policy exists and it's unlocked. By default, any previous versions that are created after the policy is configured will inherit the policy on the current version of the blob. For more information, see Configure a retention policy on the current version of a blob.
  • Option 3: You can configure a policy on a previous version of a blob. This policy can override a default policy configured on the current version, if one exists and it's unlocked. For more information, see Configure a retention policy on a previous version of a blob.

For more information on blob versioning, see Blob versioning.

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.

    Screenshot showing how to configure a retention policy for the current version of a 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.

Screenshot showing immutability policy properties on blob version in Azure portal

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.

    Screenshot showing how to configure retention policy for a previous blob version in Azure portal

Configure a time-based retention policy when uploading a blob

When you use the Azure portal to upload a blob to a container that supports version-level immutability, you have several options for configuring a time-based retention policy for the new blob:

  • Option 1: If a default retention policy is configured for the container, you can upload the blob with the container's policy. This option is selected by default when there's a retention policy on the container.
  • Option 2: If a default retention policy is configured for the container, you can choose to override the default policy, either by defining a custom retention policy for the new blob, or by uploading the blob with no policy.
  • Option 3: If no default policy is configured for the container, then you can upload the blob with a custom policy, or with no policy.

To configure a time-based retention policy when you upload a blob, follow these steps:

  1. Navigate to the desired container, and select Upload.

  2. In the Upload blob dialog, expand the Advanced section.

  3. Configure the time-based retention policy for the new blob in the Retention policy field. If there's a default policy configured for the container, that policy is selected by default. You can also specify a custom policy for the blob.

    Screenshot showing options for configuring retention policy on blob upload in Azure portal

Modify or delete an unlocked retention policy

You can modify an unlocked time-based retention policy to shorten or lengthen the retention interval. You can also delete an unlocked policy. Editing or deleting an unlocked time-based retention policy for a blob version doesn't affect policies in effect for any other versions. If there's a default time-based retention policy in effect for the container, then the blob version with the modified or deleted policy will no longer inherit from the container.

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.

    Screenshot showing how to edit an existing version-level time-based retention policy in Azure portal

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

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

Lock a time-based retention policy

When you have finished testing a time-based retention policy, you can lock the policy. A locked policy is compliant with SEC 17a-4(f) and other regulatory compliance. You can lengthen the retention interval for a locked policy up to five times, but you can't shorten it.

After a policy is locked, you can't delete it. However, you can delete the blob after the retention interval has expired.

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.

    Screenshot showing how to lock a time-based retention policy in Azure portal

A legal hold stores immutable data until the legal hold is explicitly cleared. To learn more about legal hold policies, see Legal holds for immutable blob data.

To configure a legal hold on a blob version, you must first enable version-level immutability support on the storage account or container. For more information, see Enable support for version-level immutability.

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.

Screenshot showing legal hold configured for blob version

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

Next steps