Add preflight information

Author: mumian

articles/azure-resource-manager/bicep/deploy-preflight.md

@@ -0,0 +1,69 @@
+---
+title: 'Preflight: Server-side validation before deployment'
+description: Server‑side validation phase that runs after the template is submitted but before any resources are created or modified.
+ms.topic: article
+ms.date: 03/04/2026
+---
+
+# Preflight: Server validation before deployment
+
+Preflight is the server validation phase that runs after you submit the template but before Azure creates or modifies any resources.
+
+To understand preflight, it helps to see where it fits compared to other checks:
+
+1. [**Linting (Static Check)**](./linter.md): Checks syntax and best practices (for example, "You have an unused variable") while you type in VS Code.
+2. **Deployment Validation (The "Dry Run")**: This step is preflight. It sends your template to Azure to see if Azure Resource Manager (ARM) accepts the configuration.
+3. [**What-If**](./deploy-what-if.md): Predicts exactly which resources are created, modified, or deleted.
+4. [**Deployment**](./deploy-cli.md): The actual execution where Azure builds the resources.
+
+When you trigger a preflight check, Azure doesn't just look at the code. It looks at the live environment and the resource provider (the service responsible for the specific resource, like Microsoft.Compute). It verifies:
+
+- Parameter values (types, allowed values, missing required parameters)
+- Resource name conflicts (for example, globally unique names already taken)
+- Scope correctness (resource group versus subscription versus tenant)
+- RBAC permissions (whether you can deploy those resource types)
+- Basic provider and API compatibility
+
+If any of these checks fail, the deployment never starts.
+
+## Limitations
+
+- Runtime errors: Preflight can't catch everything. For example, if a custom script extension fails during execution because of a typo inside a bash script, preflight won't see that error.
+- Dependent values: If Resource B depends on a property generated by Resource A (like a dynamic IP address), preflight might only perform a partial check because that value doesn't exist yet.
+
+## Run preflight
+
+Preflight validation runs automatically when you use deployment validate or what-if style commands. For example, preflight validation runs during these operations:
+
+- ARM JSON or Bicep validation in Azure CLI or PowerShell
+
+    # [Azure CLI](#tab/azure-cli)
+    
+    ```azurecli
+    az deployment group validate \
+      --resource-group myResourceGroup \
+      --template-file main.bicep
+    ```
+    
+    # [PowerShell](#tab/azure-powershell)
+    
+    ```azurepowershell
+    Test-AzResourceGroupDeployment `
+      -ResourceGroupName myResourceGroup `
+      -TemplateFile ./main.bicep
+    ```
+
+    For more information, see [Deploy Bicep files with the Azure CLI](./deploy-cli.md) and [Deploy Bicep files with the Azure PowerShell](./deploy-powershell.md).
+
+- what-if
+    What-if includes preflight checks before calculating changes unless you configure it to skip the preflight. For more information, see [Running the what-if operation](./deploy-what-if.md#running-the-what-if-operation).
+
+- Azure portal "Review + create" step
+
+    Currently, the Azure portal only supports deploying ARM JSON templates. For more information, see [Deploy ARM templates with the Azure portal](../templates/deploy-portal.md).
+
+Preflight errors appear in the Activity Log but not in deployment history, because the deployment never began.
+
+## Next steps
+
+- To use the what-if operation, see [Bicep What-If: Preview Changes Before Deployment](./deploy-what-if.md)

articles/azure-resource-manager/bicep/deploy-what-if.md

@@ -78,7 +78,7 @@ Azure CLI version **2.76.0 or later** introduces the `--validation-level` switch
 
 - **Provider** (default): Performs full validation, including template syntax, resource definitions, dependencies, and permission checks to ensure you have sufficient permissions to deploy all resources in the template. 
 - **ProviderNoRbac**: Performs full validation of the template and resources, similar to Provider, but only checks for read permissions on each resource instead of full deployment permissions. This is useful when you want to validate resource configurations without requiring full access.
-- **Template**: Performs static validation only, checking template syntax and structure while skipping preflight checks (for example, resource availability) and permission checks. This is less thorough, potentially missing issues that could cause deployment failures.
+- **Template**: Performs static validation only, checking template syntax and structure while skipping [preflight checks](./deploy-preflight.md) (for example, resource availability) and permission checks. This is less thorough, potentially missing issues that could cause deployment failures.
 
 You can use the `--confirm-with-what-if` switch (or its short form `-c`) to preview the changes and get prompted to continue with the deployment. Add this switch to:
 
@@ -104,7 +104,7 @@ Azure PowerShell version **13.4.0 or later** introduces the `-ValidationLevel` s
 
 - **Provider** (default): Performs full validation, including template syntax, resource definitions, dependencies, and permission checks to ensure you have sufficient permissions to deploy all resources in the template.
 - **ProviderNoRbac**: Performs full validation of the template and resources, similar to Provider, but only checks for read permissions on each resource instead of full deployment permissions. This is useful when you want to validate resource configurations without requiring full access.
-- **Template**: Performs static validation only, checking template syntax and structure while skipping preflight checks (for example, resource availability) and permission checks. This is less thorough, potentially missing issues that could cause deployment failures.
+- **Template**: Performs static validation only, checking template syntax and structure while skipping [preflight checks](./deploy-preflight.md) (for example, resource availability) and permission checks. This is less thorough, potentially missing issues that could cause deployment failures.
 
 You can use the `-Confirm` switch parameter to preview the changes and get prompted to continue with the deployment.
 

articles/azure-resource-manager/bicep/toc.yml

@@ -588,6 +588,9 @@ items:
           - name: What-if check
             href: deploy-what-if.md
             displayName: whatif, what if
+          - name: Preflight check
+            href: deploy-preflight.md
+            displayName: preflight, pre-flight
           - name: Deploy - VS Code
             href: deploy-vscode.md
             displayName: visual studio code,vscode

articles/azure-resource-manager/troubleshooting/quickstart-troubleshoot-arm-deployment.md

@@ -15,7 +15,7 @@ This quickstart describes how to troubleshoot Azure Resource Manager template (A
 There are three types of errors that are related to a deployment:
 
 - **Validation errors** occur before a deployment begins and are caused by syntax errors in your file. A code editor like Visual Studio Code can identify these errors.
-- **Preflight validation errors** occur when a deployment command is run but resources aren't deployed. These errors are found without starting the deployment. For example, if a parameter value is incorrect, the error is found in preflight validation.
+- **Preflight validation errors** occur when a deployment command is run but resources aren't deployed. These errors are found without starting the deployment. For example, if a parameter value is incorrect, the error is found in [preflight validation](../bicep/deploy-preflight.md).
 - **Deployment errors** occur during the deployment process and can only be found by assessing the deployment's progress in your Azure environment.
 
 All types of errors return an error code that you use to troubleshoot the deployment. Validation and preflight errors are shown in the activity log but don't appear in your deployment history.

articles/azure-resource-manager/troubleshooting/quickstart-troubleshoot-bicep-deployment.md

@@ -13,7 +13,7 @@ This quickstart describes how to troubleshoot Bicep file deployment errors. You'
 There are three types of errors that are related to a deployment:
 
 - **Validation errors** occur before a deployment begins and are caused by syntax errors in your file. A code editor like Visual Studio Code can identify these errors.
-- **Preflight validation errors** occur when a deployment command is run but resources aren't deployed. These errors are found without starting the deployment. For example, if a parameter value is incorrect, the error is found in preflight validation.
+- **Preflight validation errors** occur when a deployment command is run but resources aren't deployed. These errors are found without starting the deployment. For example, if a parameter value is incorrect, the error is found in [preflight validation](../bicep/deploy-preflight.md).
 - **Deployment errors** occur during the deployment process and can only be found by assessing the deployment's progress in your Azure environment.
 
 All types of errors return an error code that you use to troubleshoot the deployment. Validation and preflight errors are shown in the activity log but don't appear in your deployment history. A Bicep file with syntax errors doesn't compile into JSON and isn't shown in the activity log.