Add paid bursting to billing and create file share documents.

Author: wmgries

articles/storage/files/storage-how-to-create-file-share.md

@@ -531,8 +531,15 @@ $provisionedIops = 10000
 $provisionedThroughputMibPerSec = 2048
 
 # Update the file share provisioning.
-Update-AzRmStorageShare -ResourceGroupName $resourceGroupName -AccountName $storageAccountName -ShareName $shareName -ProvisionedBandwidthMibps $provisionedThroughputMibPerSec -ProvisionedIops $provisionedIops -QuotaGiB $provisionedStorageGib;
-$f = Get-AzRmStorageShare -ResourceGroupName $resourceGroupName -AccountName $storageAccountName -ShareName $shareName;
+Update-AzRmStorageShare `
+        -ResourceGroupName $resourceGroupName `
+        -AccountName $storageAccountName `
+        -ShareName $shareName `
+        -QuotaGiB $provisionedStorageGib `
+        -ProvisionedIops $provisionedIops `
+        -ProvisionedBandwidthMibps $provisionedThroughputMibPerSec
+
+$f = Get-AzRmStorageShare -ResourceGroupName $resourceGroupName -AccountName $storageAccountName -ShareName $shareName
 $f | fl
 ```
 
@@ -552,8 +559,13 @@ provisionedIops=10000
 provisionedThroughputMibPerSec=2048
 
 # Update the file share provisioning.
-az storage share-rm update --resource-group $resourceGroupName --name $shareName --storage-account $storageAccountName --quota $provisionedStorageGib --provisioned-iops $provisionedIops --provisioned-bandwidth-mibps $provisionedThroughputMibPerSec
-
+az storage share-rm update \
+        --resource-group $resourceGroupName \
+        --name $shareName \
+        --storage-account $storageAccountName \
+        --quota $provisionedStorageGib \
+        --provisioned-iops $provisionedIops \
+        --provisioned-bandwidth-mibps $provisionedThroughputMibPerSec
 ```
 
 ---
@@ -578,24 +590,54 @@ Follow these instructions to update the provisioning for your file share.
 
 5. Select **Save** to save provisioning changes. Storage, IOPS, and throughput changes are effective within a few minutes after a provisioning change.
 
+> [!NOTE]
+> You can use PowerShell and CLI to enable/disable paid bursting if desired. Paid burst is an advanced feature of the provisioned v1 billing model, consult [provisioned v1 paid bursting](./understanding-billing.md#provisioned-v1-paid-bursting) before enabling.
+
 # [PowerShell](#tab/azure-powershell)
-You can modify a provisioned v1 file share with the `Update-AzRmStorageShare` cmdlet. Remember to replace the values for the variables `$resourceGroupName`, `$storageAccountName`, `$fileShareName`, and `$provisionedStorageGib` with the desired values for your file share.
+You can modify a provisioned v1 file share with the `Update-AzRmStorageShare` cmdlet. Remember to replace the values for the variables `$resourceGroupName`, `$storageAccountName`, and `$fileShareName` with the desired values for your file share. Set `$provisionedStorageGib`, `$paidBurstingEnabled`, `$paidBurstingMaxIops`, and `$paidBurstingMaxThroughputMibPerSec` to non-null (`$null`) values to set on the file share. Paid bursting is an advanced feature of the provisioned v1 model, consult [provisioned v1 paid bursting](./understanding-billing.md#provisioned-v1-paid-bursting) before enabling.
 
 ```PowerShell
 # The path to the file share resource to be modified.
 $resourceGroupName = "<resource-group>"
 $storageAccountName = "<storage-account>"
 $fileShareName = "<file-share>"
 
-# The provisioning desired on the file share.
-$provisionedStorageGib = 10240
+# The provisioning desired on the file share. Set to $null to keep at the 
+# current level of provisioning.
+$provisionedStorageGib = 10240 
+
+# Paid bursting settings.
+$paidBurstingEnabled = $null # Set to $true or $false.
+$paidBurstingMaxIops = $null # Set to an integer value.
+$paidBurstingMaxThroughputMibPerSec = $null # Set to an integer value.
+
+# Configure parameter object for splatting.
+$params = @{
+    ResourceGroupName = $resourceGroupName;
+    StorageAccountName = $storageAccountName;
+    Name = $fileShareName;
+}
+
+if ($null -ne $provisionedStorageGib) { 
+    $params += @{ QuotaGiB = $provisionedStorageGib }
+}
+
+if ($null -ne $paidBurstingEnabled) {
+    $params += @{ PaidBurstingEnabled = $paidBurstingEnabled }
+}
+
+if ($null -ne $paidBurstingMaxIops) {
+    $params += @{ PaidBurstingMaxIops = $paidBurstingMaxIops }
+}
+
+if ($null -ne $paidBurstingMaxThroughputMibPerSec) {
+    $params += @{ 
+        PaidBurstingMaxBandwidthMibps = $paidBurstingMaxThroughputMibPerSec 
+    }
+}
 
 # Update the file share provisioning.
-Update-AzRmStorageShare `
-        -ResourceGroupName $resourceGroupName `
-        -StorageAccountName $storageAccountName `
-        -Name $fileShareName `
-        -QuotaGiB $provisionedStorageGib
+Update-AzRmStorageShare @params
 ```
 
 # [Azure CLI](#tab/azure-cli)
@@ -618,6 +660,20 @@ az storage share-rm update \
         --quota $provisionedStorageGib
 ```
 
+To toggle paid bursting, use the `--paid-bursting-enabled` parameter. Paid bursting is an advanced feature of the provisioned v1 model, consult [provisioned v1 paid bursting](./understanding-billing.md#provisioned-v1-paid-bursting) before enabling. You can optionally use the `--paid-bursting-max-iops` and `--paid-bursting-max-bandwidth-mibps` flags to set a restriction on the upper amount of paid bursting allowed for cost control purposes. Remember to replace the values for the variables `resourceGroupName`, `storageAccountName`, and `fileShareName` with the desired values for your file share.
+
+```bash
+resourceGroupName="<resource-group>"
+storageAccountName="<storage-account>"
+fileShareName="<file-share>"
+
+az storage share-rm update \
+        --resource-group $resourceGroupName \
+        --storage-account $storageAccountName \
+        --name $fileShareName \
+        --paid-bursting-enabled true
+```
+
 ---
 
 ### Change the cost and performance characteristics of a pay-as-you-go file share

articles/storage/files/understanding-billing.md

@@ -4,7 +4,7 @@ description: Learn how to interpret the provisioned and pay-as-you-go billing mo
 author: khdownie
 ms.service: azure-file-storage
 ms.topic: conceptual
-ms.date: 01/23/2025
+ms.date: 03/11/2025
 ms.author: kendownie
 ms.custom: references_regions
 ---
@@ -270,6 +270,9 @@ The amount of IOPS and throughput provisioned on the share are determined by the
 Depending on your individual file share requirement, you may find that you require more IOPS or throughput than our provisioning formulas provide. In this case, you will need to provision more storage to get the required IOPS or throughput.
 
 ### Provisioned v1 bursting
+The provisioned v1 model supports two types of bursting: credit-based bursting, which is included for free as a part of the provisioning, and paid bursting, which is an advanced feature that can optionally be enabled to support usage-based billing whenever the IOPS and throughput go over the provisioned amount.
+
+#### Provisioned v1 credit-based bursting
 Credit-based IOPS bursting provides added flexibility around IOPS usage. This flexibility is best used as a buffer against unanticipated IO-spikes. For established IO patterns, we recommend provisioning for IO peaks.
 
 Burst IOPS credits accumulate whenever traffic for your file share is below provisioned (baseline) IOPS. Whenever a file share's IOPS usage exceeds the provisioned IOPS and there are available burst IOPS credits, the file share can burst up to the maximum allowed burst IOPS limit. File shares can continue to burst as long as there are credits remaining, but this is based on the number of burst credits accrued. Each IO beyond provisioned IOPS consumes one credit. Once all credits are consumed, the share returns to the provisioned IOPS. IOPS against the file share don't have to do anything special to use bursting. Bursting operates on a best effort basis.  
@@ -300,7 +303,20 @@ The following table illustrates a few examples of these formulas for the provisi
 | 51,200 | 54,200 | Up to 102,400 | 164,880,000 | 5,220 |
 | 102,400 | 102,400 | Up to 102,400 | 0 | 10,340 |
 
-Effective file share performance is subject to machine network limits, available network bandwidth, IO sizes, and parallelism, among many other factors. To achieve maximum benefit from parallelization, we recommend enabling [SMB Multichannel](files-smb-protocol.md#smb-multichannel) on SSD file shares. Refer to [SMB performance](smb-performance.md) and [performance troubleshooting guide](/troubleshoot/azure/azure-storage/files-troubleshoot-performance?toc=/azure/storage/files/toc.json) for some common performance issues and workarounds.
+#### Provisioned v1 paid bursting
+Paid bursting is an advanced feature of the provisioned v1 model designed to support customers who never want to be throttled. Unlike credit-based bursting which is included for free as part of provisioned storage, paid bursting adds additional usage-based billing for any amount of IOPS or throughput above the provisioned storage. While this can add powerful flexibility to how you provision your file share, it can also lead to unexpected billing if used incorrectly.
+
+Like credit-based bursting, paid bursting is not a replacement for provisioning the correct amount of IOPS and throughput, but rather an additional protection against throttling in the case of unexpected demand. If you have a consistent level of IOPS or throughput usage, it is cheaper to provision enough IOPS and throughput (through storage provisioning) to cover demand instead relying on paid bursting.
+
+Paid bursting is disabled by default, but can be enabled following the instructions to [change the cost and performance characteristics of a provisioned v1 file share](./storage-how-to-create-file-share.md?tabs=azure-powershell#change-the-cost-and-performance-characteristics-of-a-provisioned-v1-file-share) (PowerShell and CLI only). If paid bursting is enabled, we recommend carefully monitoring IOPS and throughput usage using the following metrics available through Azure monitor:
+
+- File Share Provisioned IOPS
+- File Share Provisioned Bandwidth MiB/s (throughput)
+- Transactions by Max IOPS
+- Bandwidth by Max MiB/sec (throughput)
+- Burst Credits for IOPS (credit-based bursting)
+- Paid Bursting IOS (IOs)
+- Paid Bursting Bandwidth
 
 ### Provisioned v1 snapshots
 Azure Files supports snapshots, which are similar to volume shadow copies (VSS) on Windows File Server. For more information on share snapshots, see [Overview of snapshots for Azure Files](storage-snapshots-files.md).