Merge pull request #204914 from normesta/immutability

Immutability policies

Author: 19BMG00

articles/storage/blobs/data-protection-overview.md

@@ -1,20 +1,20 @@
 ---
 title: Legal holds for immutable blob data
 titleSuffix: Azure Storage
-description: A legal hold stores blob data in a Write-Once, Read-Many (WORM) format until it is explicitly cleared. Use a legal hold when the period of time that the data must be kept in a WORM state is unknown.
+description: A legal hold stores blob data in a Write-Once, Read-Many (WORM) format until it's explicitly cleared. Use a legal hold when the period of time that the data must be kept in a WORM state is unknown.
 services: storage
 author: normesta
 
 ms.service: storage
 ms.topic: conceptual
-ms.date: 12/01/2021
+ms.date: 09/14/2022
 ms.author: normesta
 ms.subservice: blobs
 ---
 
 # Legal holds for immutable blob data
 
-A legal hold is a temporary immutability policy that can be applied for legal investigation purposes or general protection policies. A legal hold stores blob data in a Write-Once, Read-Many (WORM) format until it is explicitly cleared. When a legal hold is in effect, blobs can be created and read, but not modified or deleted. Use a legal hold when the period of time that the data must be kept in a WORM state is unknown.
+A legal hold is a temporary immutability policy that can be applied for legal investigation purposes or general protection policies. A legal hold stores blob data in a Write-Once, Read-Many (WORM) format until it's explicitly cleared. When a legal hold is in effect, blobs can be created and read, but not modified or deleted. Use a legal hold when the period of time that the data must be kept in a WORM state is unknown.
 
 For more information about immutability policies for Blob Storage, see [Store business-critical blob data with immutable storage](immutable-storage-overview.md).
 
@@ -23,11 +23,11 @@ For more information about immutability policies for Blob Storage, see [Store bu
 A legal hold policy can be configured at either of the following scopes:
 
 - Version-level policy: A legal hold can be configured on an individual blob version level for granular management of sensitive data.
-- Container-level policy: A legal hold that is configured at the container level applies to all blobs in that container. Individual blobs cannot be configured with their own immutability policies.
+- Container-level policy: A legal hold that is configured at the container level applies to all blobs in that container. Individual blobs can't be configured with their own immutability policies.
 
 ### Version-level policy scope
 
-To configure a legal hold on a blob version, you must first enable version-level immutability on the storage account or the parent container. Version-level immutability cannot be disabled after it is enabled. For more information, [Enable support for version-level immutability](immutable-policy-configure-version-scope.md#enable-support-for-version-level-immutability).
+To configure a legal hold on a blob version, you must first enable version-level immutability on the storage account or the parent container. Version-level immutability can't be disabled after it's enabled. For more information, [Enable support for version-level immutability](immutable-policy-configure-version-scope.md#enable-support-for-version-level-immutability).
 
 After version-level immutability is enabled for a storage account or a container, a legal hold can no longer be set at the container level. Legal holds must be applied to individual blob versions. A legal hold may be configured for the current version or a previous version of a blob.
 
@@ -37,9 +37,9 @@ To learn more about enabling a version-level legal hold, see [Configure or clear
 
 ### Container-level scope
 
-When you configure a legal hold for a container, that hold applies to all objects in the container. When the legal hold is cleared, clients can once again write and delete objects in the container, unless there is also a time-based retention policy in effect for the container.
+A legal hold for a container applies to all objects in the container. When the legal hold is cleared, clients can once again write and delete objects in the container, unless there's also a time-based retention policy in effect for the container.
 
-When a legal hold is applied to a container, all existing blobs move into an immutable WORM state in less than 30 seconds. All new blobs that are uploaded to that policy-protected container will also move into an immutable state. Once all blobs are in an immutable state, overwrite or delete operations in the immutable container are not allowed. In the case of an account with a hierarchical namespace, blobs cannot be renamed or moved to a different directory.
+When a legal hold is applied to a container, all existing blobs move into an immutable WORM state in less than 30 seconds. All new blobs that are uploaded to that policy-protected container will also move into an immutable state. Once all blobs are in an immutable state, overwrite or delete operations in the immutable container aren't allowed. In an account that has a hierarchical namespace, blobs can't be renamed or moved to a different directory.
 
 To learn how to configure a legal hold with container-level scope, see [Configure or clear a legal hold](immutable-policy-configure-container-scope.md#configure-or-clear-a-legal-hold).
 
@@ -51,16 +51,27 @@ A container-level legal hold must be associated with one or more user-defined al
 
 Each container with a legal hold in effect provides a policy audit log. The log contains the user ID, command type, time stamps, and legal hold tags. The audit log is retained for the lifetime of the policy, in accordance with the SEC 17a-4(f) regulatory guidelines.
 
-The [Azure Activity log](../../azure-monitor/essentials/platform-logs-overview.md) provides a more comprehensive log of all management service activities. [Azure resource logs](../../azure-monitor/essentials/platform-logs-overview.md) retain information about data operations. It is the user's responsibility to store those logs persistently, as might be required for regulatory or other purposes.
+The [Azure Activity log](../../azure-monitor/essentials/platform-logs-overview.md) provides a more comprehensive log of all management service activities. [Azure resource logs](../../azure-monitor/essentials/platform-logs-overview.md) retain information about data operations. It's the user's responsibility to store those logs persistently, as might be required for regulatory or other purposes.
 
 #### Limits
 
 The following limits apply to container-level legal holds:
 
 - For a storage account, the maximum number of containers with a legal hold setting is 10,000.
-- For a container, the maximum number of legal hold tags is ten.
+- For a container, the maximum number of legal hold tags is 10.
 - The minimum length of a legal hold tag is three alphanumeric characters. The maximum length is 23 alphanumeric characters.
-- For a container, a maximum of ten legal hold policy audit logs are retained for the duration of the policy.
+- For a container, a maximum of 10 legal hold policy audit logs are retained for the duration of the policy.
+
+## Allow protected append blobs writes
+
+Append blobs are composed of blocks of data and optimized for data append operations required by auditing and logging scenarios. By design, append blobs only allow the addition of new blocks to the end of the blob. Regardless of immutability, modification or deletion of existing blocks in an append blob is fundamentally not allowed. To learn more about append blobs, see [About Append Blobs](/rest/api/storageservices/understanding-block-blobs--append-blobs--and-page-blobs#about-append-blobs).
+
+The **AllowProtectedAppendWritesAll** property setting allows for writing new blocks to an append blob while maintaining immutability protection and compliance. If this setting is enabled, you can create an append blob directly in the policy-protected container, and then continue to add new blocks of data to the end of the append blob with the Append Block operation. Only new blocks can be added; any existing blocks can't be modified or deleted. Enabling this setting doesn't affect the immutability behavior of block blobs or page blobs. 
+
+> [!NOTE]
+> This property is available only for container-level policies. This property is not available for version-level policies.
+
+This setting also adds the ability to write new blocks to a block blob. The Blob Storage API doesn't 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.
 
 ## Next steps
 

articles/storage/blobs/immutable-legal-hold-overview.md

@@ -7,7 +7,7 @@ author: normesta
 
 ms.service: storage
 ms.topic: how-to
-ms.date: 12/01/2021
+ms.date: 09/14/2022
 ms.author: normesta
 ms.subservice: blobs
 ms.custom: devx-track-azurepowershell, devx-track-azurecli 
@@ -32,11 +32,22 @@ To configure a time-based retention policy on a container, use the Azure portal,
 To configure a time-based retention policy on a container with the Azure portal, follow these steps:
 
 1. Navigate to the desired container.
-1. Select the **More** button on the right, then select **Access policy**.
-1. In the **Immutable blob storage** section, select **Add policy**.
-1. In the **Policy type** field, select **Time-based retention**, and specify the retention period in days.
-1. To create a policy with container scope, do not check the box for **Enable version-level immutability**.
-1. If desired, select **Allow additional protected appends** to enable writes to append blobs that are protected by an immutability policy. For more information, see [Allow protected append blobs writes](immutable-time-based-retention-policy-overview.md#allow-protected-append-blobs-writes).
+
+2. Select the **More** button on the right, then select **Access policy**.
+
+3. In the **Immutable blob storage** section, select **Add policy**.
+
+4. In the **Policy type** field, select **Time-based retention**, and specify the retention period in days.
+
+5. To create a policy with container scope, do not check the box for **Enable version-level immutability**.
+
+6. 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](/rest/api/storageservices/append-block) operation.
+
+   The **Block and append blobs** option provides you with the same permissions as the **Append blobs** option but adds 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, some Microsoft applications use internal APIs to create block blobs and then append to them. 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 blocks to a block blob. 
+
+   To learn more about these options, see [Allow protected append blobs writes](immutable-time-based-retention-policy-overview.md#allow-protected-append-blobs-writes).
 
     :::image type="content" source="media/immutable-policy-configure-container-scope/configure-retention-policy-container-scope.png" alt-text="Screenshot showing how to configure immutability policy scoped to container":::
 
@@ -55,6 +66,14 @@ Set-AzRmStorageContainerImmutabilityPolicy -ResourceGroupName <resource-group> `
     -ImmutabilityPeriod 10
 ```
 
+To allow protected append writes, set the `-AllowProtectedAppendWrite` or  `-AllowProtectedAppendWriteAll` parameter to `true`. 
+
+The **AllowProtectedAppendWrite** option enables your workloads to add new blocks of data to the end of an append blob by using the [Append Block](/rest/api/storageservices/append-block) operation.
+
+The **AllowProtectedAppendWriteAll** option provides you with the same permissions as the **AllowProtectedAppendWrite** option but adds 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, some Microsoft applications use internal APIs to create block blobs and then append to them. 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 blocks to a block blob.
+
+To learn more about these options, see [Allow protected append blobs writes](immutable-time-based-retention-policy-overview.md#allow-protected-append-blobs-writes).
+
 ### [Azure CLI](#tab/azure-cli)
 
 To configure a time-based retention policy on a container with Azure CLI, call the [az storage container immutability-policy create](/cli/azure/storage/container/immutability-policy#az-storage-container-immutability-policy-create) command, providing the retention interval in days. Remember to replace placeholder values in angle brackets with your own values:
@@ -67,6 +86,14 @@ az storage container immutability-policy create \
     --period 10
 ```
 
+To allow protected append writes, set the `--allow-protected-append-writes` or  `--allow-protected-append-writes-all` parameter to `true`. 
+
+The **--allow-protected-append-writes** option enables your workloads to add new blocks of data to the end of an append blob by using the [Append Block](/rest/api/storageservices/append-block) operation.
+
+The **--allow-protected-append-writes-all** option provides you with the same permissions as the **--allow-protected-append-writes** option but adds 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, some Microsoft applications use internal APIs to create block blobs and then append to them. 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 blocks to a block blob.
+
+To learn more about these options, see [Allow protected append blobs writes](immutable-time-based-retention-policy-overview.md#allow-protected-append-blobs-writes).
+
 ---
 
 ## Modify an unlocked retention policy
@@ -102,7 +129,7 @@ Set-AzRmStorageContainerImmutabilityPolicy -ResourceGroupName <resource-group> `
     -StorageAccountName <storage-account> `
     -ContainerName <container> `
     -ImmutabilityPeriod 21 `
-    -AllowProtectedAppendWrite true `
+    -AllowProtectedAppendWriteAll true `
     -Etag $policy.Etag `
     -ExtendPolicy
 ```
@@ -133,7 +160,7 @@ az storage container immutability-policy extend \
     --container-name <container> \
     --period 21 \
     --if-match $etag \
-    --allow-protected-append-writes true
+    --allow-protected-append-writes-all true
 ```
 
 To delete an unlocked policy, call the [az storage container immutability-policy delete](/cli/azure/storage/container/immutability-policy#az-storage-container-immutability-policy-delete) command.
@@ -200,9 +227,26 @@ A legal hold stores immutable data until the legal hold is explicitly cleared. T
 To configure a legal hold on a container with the Azure portal, follow these steps:
 
 1. Navigate to the desired container.
-1. Select the **More** button and choose **Access policy**.
-1. Under the **Immutable blob versions** section, select **Add policy**.
-1. Choose **Legal hold** as the policy type, and select **OK** to apply it.
+
+2. Select the **More** button and choose **Access policy**.
+
+3. Under the **Immutable blob versions** section, select **Add policy**.
+
+4. Choose **Legal hold** as the policy type.
+
+5. Add one or more legal hold tags.
+
+6. Choose whether to allow protected append writes, and then select **Save**.
+
+   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](/rest/api/storageservices/append-block) operation.
+
+   This setting also adds 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](immutable-legal-hold-overview.md#allow-protected-append-blobs-writes).
+
+    :::image type="content" source="media/immutable-policy-configure-container-scope/configure-retention-policy-container-scope-legal-hold.png" alt-text="Screenshot showing how to configure legal hold policy scoped to container.":::
+
+After you've configured the immutability policy, you will see that it is scoped to the container:
 
 The following image shows a container with both a time-based retention policy and legal hold configured.
 
@@ -218,7 +262,8 @@ To configure a legal hold on a container with PowerShell, call the [Add-AzRmStor
 Add-AzRmStorageContainerLegalHold -ResourceGroupName <resource-group> `
     -StorageAccountName <storage-account> `
     -Name <container> `
-    -Tag <tag1>,<tag2>,...
+    -Tag <tag1>,<tag2>,...`
+    -AllowProtectedAppendWriteAll true
 ```
 
 To clear a legal hold, call the [Remove-AzRmStorageContainerLegalHold](/powershell/module/az.storage/remove-azrmstoragecontainerlegalhold) command:
@@ -239,7 +284,8 @@ az storage container legal-hold set \
     --tags tag1 tag2 \
     --container-name <container> \
     --account-name <storage-account> \
-    --resource-group <resource-group>
+    --resource-group <resource-group> \
+    --allow-protected-append-writes-all true
 ```
 
 To clear a legal hold, call the [az storage container legal-hold clear](/cli/azure/storage/container/legal-hold#az-storage-container-legal-hold-clear) command:
@@ -249,7 +295,7 @@ az storage container legal-hold clear \
     --tags tag1 tag2 \
     --container-name <container> \
     --account-name <storage-account> \
-    --resource-group <resource-group>
+    --resource-group <resource-group> \ 
 ```
 
 ---