Deployments - What If

Returns changes that will be made by the deployment if executed at the scope of the resource group.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}/whatIf?api-version=2021-04-01

URI Parameters

Name In Required Type Description
deploymentName
path True

string

The name of the deployment.

Regex pattern: ^[-\w\._\(\)]+$

resourceGroupName
path True

string

The name of the resource group the template will be deployed to. The name is case insensitive.

Regex pattern: ^[-\w\._\(\)]+$

subscriptionId
path True

string

The Microsoft Azure subscription ID.

api-version
query True

string

The API version to use for this operation.

Request Body

Name Required Type Description
properties True

DeploymentWhatIfProperties

The deployment properties.

location

string

The location to store the deployment data.

Responses

Name Type Description
200 OK

WhatIfOperationResult

OK - Returns What-If operation status

202 Accepted

Accepted - Returns URL in Location header to query for long-running operation status.

Headers

  • Location: string
  • Retry-After: string
Other Status Codes

CloudError

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Predict template changes at resource group scope

Sample request

POST https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000001/resourcegroups/my-resource-group/providers/Microsoft.Resources/deployments/my-deployment/whatIf?api-version=2021-04-01

{
  "properties": {
    "templateLink": {
      "uri": "https://example.com/exampleTemplate.json"
    },
    "parameters": {},
    "mode": "Incremental"
  }
}

Sample response

{
  "status": "Succeeded",
  "properties": {
    "changes": [
      {
        "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myExistingIdentity",
        "changeType": "Modify",
        "before": {
          "apiVersion": "2018-11-30",
          "id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myExistingIdentity",
          "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
          "name": "myExistingIdentity",
          "location": "westus2"
        },
        "after": {
          "apiVersion": "2018-11-30",
          "id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myExistingIdentity",
          "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
          "name": "myExistingIdentity",
          "location": "westus2",
          "tags": {
            "myNewTag": "my tag value"
          }
        },
        "delta": [
          {
            "path": "tags.myNewTag",
            "propertyChangeType": "Create",
            "after": "my tag value"
          }
        ]
      },
      {
        "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myNewIdentity",
        "changeType": "Create",
        "after": {
          "apiVersion": "2018-11-30",
          "id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myNewIdentity",
          "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
          "name": "myNewIdentity",
          "location": "eastus",
          "tags": {
            "myOtherNewTag": "another new tag value"
          }
        }
      }
    ]
  }
}
Location: /subscriptions/00000000-0000-0000-0000-000000000000/ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ

Definitions

Name Description
ChangeType

Type of change that will be made to the resource when the deployment is executed.

CloudError

An error response for a resource management request.

DebugSetting

The debug setting.

DeploymentMode

The mode that is used to deploy resources. This value can be either Incremental or Complete. In Incremental mode, resources are deployed without deleting existing resources that are not included in the template. In Complete mode, resources are deployed and existing resources in the resource group that are not included in the template are deleted. Be careful when using Complete mode as you may unintentionally delete resources.

DeploymentWhatIf

Deployment What-if operation parameters.

DeploymentWhatIfProperties

Deployment What-if properties.

DeploymentWhatIfSettings

Deployment What-If operation settings.

ErrorAdditionalInfo

The resource management error additional info.

ErrorResponse

Error Response

ExpressionEvaluationOptions

Specifies whether template expressions are evaluated within the scope of the parent template or nested template.

ExpressionEvaluationOptionsScopeType

The scope to be used for evaluation of parameters, variables and functions in a nested template.

OnErrorDeployment

Deployment on error behavior.

OnErrorDeploymentType

The deployment on error behavior type. Possible values are LastSuccessful and SpecificDeployment.

ParametersLink

Entity representing the reference to the deployment parameters.

PropertyChangeType

The type of property change.

TemplateLink

Entity representing the reference to the template.

WhatIfChange

Information about a single resource change predicted by What-If operation.

WhatIfOperationResult

Result of the What-If operation. Contains a list of predicted changes and a URL link to get to the next set of results.

WhatIfPropertyChange

The predicted change to the resource property.

WhatIfResultFormat

The format of the What-If results

ChangeType

Type of change that will be made to the resource when the deployment is executed.

Name Type Description
Create

string

The resource does not exist in the current state but is present in the desired state. The resource will be created when the deployment is executed.

Delete

string

The resource exists in the current state and is missing from the desired state. The resource will be deleted when the deployment is executed.

Deploy

string

The resource exists in the current state and the desired state and will be redeployed when the deployment is executed. The properties of the resource may or may not change.

Ignore

string

The resource exists in the current state and is missing from the desired state. The resource will not be deployed or modified when the deployment is executed.

Modify

string

The resource exists in the current state and the desired state and will be redeployed when the deployment is executed. The properties of the resource will change.

NoChange

string

The resource exists in the current state and the desired state and will be redeployed when the deployment is executed. The properties of the resource will not change.

Unsupported

string

The resource is not supported by What-If.

CloudError

An error response for a resource management request.

Name Type Description
error

ErrorResponse

Error Response
Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.)

DebugSetting

The debug setting.

Name Type Description
detailLevel

string

Specifies the type of information to log for debugging. The permitted values are none, requestContent, responseContent, or both requestContent and responseContent separated by a comma. The default is none. When setting this value, carefully consider the type of information you are passing in during deployment. By logging information about the request or response, you could potentially expose sensitive data that is retrieved through the deployment operations.

DeploymentMode

The mode that is used to deploy resources. This value can be either Incremental or Complete. In Incremental mode, resources are deployed without deleting existing resources that are not included in the template. In Complete mode, resources are deployed and existing resources in the resource group that are not included in the template are deleted. Be careful when using Complete mode as you may unintentionally delete resources.

Name Type Description
Complete

string

Incremental

string

DeploymentWhatIf

Deployment What-if operation parameters.

Name Type Description
location

string

The location to store the deployment data.

properties

DeploymentWhatIfProperties

The deployment properties.

DeploymentWhatIfProperties

Deployment What-if properties.

Name Type Description
debugSetting

DebugSetting

The debug setting of the deployment.

expressionEvaluationOptions

ExpressionEvaluationOptions

Specifies whether template expressions are evaluated within the scope of the parent template or nested template. Only applicable to nested templates. If not specified, default value is outer.

mode

DeploymentMode

The mode that is used to deploy resources. This value can be either Incremental or Complete. In Incremental mode, resources are deployed without deleting existing resources that are not included in the template. In Complete mode, resources are deployed and existing resources in the resource group that are not included in the template are deleted. Be careful when using Complete mode as you may unintentionally delete resources.

onErrorDeployment

OnErrorDeployment

The deployment on error behavior.

parameters

object

Name and value pairs that define the deployment parameters for the template. You use this element when you want to provide the parameter values directly in the request rather than link to an existing parameter file. Use either the parametersLink property or the parameters property, but not both. It can be a JObject or a well formed JSON string.

parametersLink

ParametersLink

The URI of parameters file. You use this element to link to an existing parameters file. Use either the parametersLink property or the parameters property, but not both.

template

object

The template content. You use this element when you want to pass the template syntax directly in the request rather than link to an existing template. It can be a JObject or well-formed JSON string. Use either the templateLink property or the template property, but not both.

templateLink

TemplateLink

The URI of the template. Use either the templateLink property or the template property, but not both.

whatIfSettings

DeploymentWhatIfSettings

Optional What-If operation settings.

DeploymentWhatIfSettings

Deployment What-If operation settings.

Name Type Description
resultFormat

WhatIfResultFormat

The format of the What-If results

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.

type

string

The additional info type.

ErrorResponse

Error Response

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorResponse[]

The error details.

message

string

The error message.

target

string

The error target.

ExpressionEvaluationOptions

Specifies whether template expressions are evaluated within the scope of the parent template or nested template.

Name Type Description
scope

ExpressionEvaluationOptionsScopeType

The scope to be used for evaluation of parameters, variables and functions in a nested template.

ExpressionEvaluationOptionsScopeType

The scope to be used for evaluation of parameters, variables and functions in a nested template.

Name Type Description
Inner

string

NotSpecified

string

Outer

string

OnErrorDeployment

Deployment on error behavior.

Name Type Description
deploymentName

string

The deployment to be used on error case.

type

OnErrorDeploymentType

The deployment on error behavior type. Possible values are LastSuccessful and SpecificDeployment.

OnErrorDeploymentType

The deployment on error behavior type. Possible values are LastSuccessful and SpecificDeployment.

Name Type Description
LastSuccessful

string

SpecificDeployment

string

Entity representing the reference to the deployment parameters.

Name Type Description
contentVersion

string

If included, must match the ContentVersion in the template.

uri

string

The URI of the parameters file.

PropertyChangeType

The type of property change.

Name Type Description
Array

string

The property is an array and contains nested changes.

Create

string

The property does not exist in the current state but is present in the desired state. The property will be created when the deployment is executed.

Delete

string

The property exists in the current state and is missing from the desired state. It will be deleted when the deployment is executed.

Modify

string

The property exists in both current and desired state and is different. The value of the property will change when the deployment is executed.

NoEffect

string

The property will not be set or updated.

Entity representing the reference to the template.

Name Type Description
contentVersion

string

If included, must match the ContentVersion in the template.

id

string

The resource id of a Template Spec. Use either the id or uri property, but not both.

queryString

string

The query string (for example, a SAS token) to be used with the templateLink URI.

relativePath

string

The relativePath property can be used to deploy a linked template at a location relative to the parent. If the parent template was linked with a TemplateSpec, this will reference an artifact in the TemplateSpec. If the parent was linked with a URI, the child deployment will be a combination of the parent and relativePath URIs

uri

string

The URI of the template to deploy. Use either the uri or id property, but not both.

WhatIfChange

Information about a single resource change predicted by What-If operation.

Name Type Description
after

object

The predicted snapshot of the resource after the deployment is executed.

before

object

The snapshot of the resource before the deployment is executed.

changeType

ChangeType

Type of change that will be made to the resource when the deployment is executed.

delta

WhatIfPropertyChange[]

The predicted changes to resource properties.

resourceId

string

Resource ID

unsupportedReason

string

The explanation about why the resource is unsupported by What-If.

WhatIfOperationResult

Result of the What-If operation. Contains a list of predicted changes and a URL link to get to the next set of results.

Name Type Description
error

ErrorResponse

Error Response
Error when What-If operation fails.

properties.changes

WhatIfChange[]

List of resource changes predicted by What-If operation.

status

string

Status of the What-If operation.

WhatIfPropertyChange

The predicted change to the resource property.

Name Type Description
after

object

The value of the property after the deployment is executed.

before

object

The value of the property before the deployment is executed.

children

WhatIfPropertyChange[]

Nested property changes.

path

string

The path of the property.

propertyChangeType

PropertyChangeType

The type of property change.

WhatIfResultFormat

The format of the What-If results

Name Type Description
FullResourcePayloads

string

ResourceIdOnly

string