Merge pull request #314533 from mumian/0309-preflight

Document preflight

Author: JamesJBarnett

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

@@ -0,0 +1,91 @@
+---
+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: 04/09/2026
+---
+
+# Preflight: Server validation before deployment
+
+In Azure Resource Manager (ARM), server-side validation consists of two distinct parts:
+
+- Static validation, which is the operation developers interact with.
+- Resource provider preflight validation, which is the internal resource provider validation phase.
+
+Static validation checks aspects of the template that ARM can evaluate without calling resource providers, such as:
+
+- Template structure and schema correctness
+- Parameter definitions and basic value constraints
+- Expression evaluation and template consistency
+
+These checks ensure the template is syntactically and structurally valid before deeper validation occurs.
+
+Preflight validation is an Azure Resource Manager (ARM) internal process executed during the validation phase. Its purpose is to accelerate error detection by preventing deployments that are known to fail. During this step, ARM invokes the relevant resource providers to verify that the deployment is feasible, without creating or modifying any resources. This part validates:
+
+- **Resource name conflicts**: During preflight, ARM evaluates the final, resolved resource names and checks whether they violate provider‑enforced uniqueness or naming rules. This check happens after expressions like `concat()` or `uniqueString()` are resolved. Preflight validation commonly fails when:
+
+  - A globally unique name (for example, a storage account name) is already taken
+  - A resource name violates provider‑specific naming constraints
+
+- **Scope correctness**: Preflight validation ensures that resources are being deployed to a valid scope and that the deployment command matches the resource types declared in the template. This validation includes:
+
+  - Whether the deployment scope (resource group, subscription, management group, tenant) is compatible with the resource types
+  - Whether required parent scopes exist. For example, deploying a resource group–scoped resource at subscription scope without a resource group.
+
+- RBAC permissions (whether you can deploy those resource types): During preflight, ARM verifies that the caller has sufficient permissions at the deployment scope to create or modify the requested resources. If the identity lacks permissions, the deployment is rejected before execution. Typical preflight permission failures include:
+
+  - Missing write permissions for a resource type
+  - Insufficient permissions at the target scope
+  - Required resource providers not registered
+
+- Basic provider and API compatibility: Preflight validation confirms that:
+
+  - The referenced resource providers are registered
+  - The specified API versions are valid and supported
+  - The resource type is recognized by Azure Resource Manager
+
+  If a provider isn't registered or the API version is invalid, ARM fails the deployment during preflight.
+
+If any of these checks fail, the deployment never starts.
+
+## Limitations
+
+Preflight validation is a best-effort process and does not catch all deployment-time errors. It cannot detect runtime failures (for example, errors within a custom script extension during execution), and its validation may be incomplete when resources depend on values that are not yet available, such as dynamically generated properties from other resources.
+
+## Run preflight
+
+Preflight validation runs automatically when you use deployment validate or what-if style commands. For example, these operations run preflight validation:
+
+- 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).
+
+- 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).
+
+- 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).
+
+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

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

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.