Deployments - What If At Subscription Scope

Service:

Resource Management

API Version:

2021-04-01

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

POST https://management.azure.com/subscriptions/{subscriptionId}/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\._\(\)]+$
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 subscription scope

Sample request

HTTP

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

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

Go

package armresources_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/resources/armresources"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/4fd842fb73656039ec94ce367bcedee25a57bd18/specification/resources/resource-manager/Microsoft.Resources/stable/2021-04-01/examples/PostDeploymentWhatIfOnSubscription.json
func ExampleDeploymentsClient_BeginWhatIfAtSubscriptionScope() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armresources.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	poller, err := clientFactory.NewDeploymentsClient().BeginWhatIfAtSubscriptionScope(ctx, "my-deployment", armresources.DeploymentWhatIf{
		Location: to.Ptr("westus"),
		Properties: &armresources.DeploymentWhatIfProperties{
			Mode:         to.Ptr(armresources.DeploymentModeIncremental),
			Parameters:   map[string]any{},
			TemplateLink: &armresources.TemplateLink{},
		},
	}, nil)
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	res, err := poller.PollUntilDone(ctx, nil)
	if err != nil {
		log.Fatalf("failed to pull the result: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res.WhatIfOperationResult = armresources.WhatIfOperationResult{
	// 	Properties: &armresources.WhatIfOperationProperties{
	// 		Changes: []*armresources.WhatIfChange{
	// 			{
	// 				After: map[string]any{
	// 					"name": "myExistingIdentity",
	// 					"type": "Microsoft.ManagedIdentity/userAssignedIdentities",
	// 					"apiVersion": "2018-11-30",
	// 					"id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myExistingIdentity",
	// 					"location": "westus2",
	// 					"tags":map[string]any{
	// 						"myNewTag": "my tag value",
	// 					},
	// 				},
	// 				Before: map[string]any{
	// 					"name": "myExistingIdentity",
	// 					"type": "Microsoft.ManagedIdentity/userAssignedIdentities",
	// 					"apiVersion": "2018-11-30",
	// 					"id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myExistingIdentity",
	// 					"location": "westus2",
	// 				},
	// 				ChangeType: to.Ptr(armresources.ChangeTypeModify),
	// 				Delta: []*armresources.WhatIfPropertyChange{
	// 					{
	// 						Path: to.Ptr("tags.myNewTag"),
	// 						After: "my tag value",
	// 						PropertyChangeType: to.Ptr(armresources.PropertyChangeTypeCreate),
	// 				}},
	// 				ResourceID: to.Ptr("/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myExistingIdentity"),
	// 			},
	// 			{
	// 				After: map[string]any{
	// 					"name": "myNewIdentity",
	// 					"type": "Microsoft.ManagedIdentity/userAssignedIdentities",
	// 					"apiVersion": "2018-11-30",
	// 					"id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myNewIdentity",
	// 					"location": "eastus",
	// 					"tags":map[string]any{
	// 						"myOtherNewTag": "another new tag value",
	// 					},
	// 				},
	// 				ChangeType: to.Ptr(armresources.ChangeTypeCreate),
	// 				ResourceID: to.Ptr("/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myNewIdentity"),
	// 			},
	// 			{
	// 				After: map[string]any{
	// 					"name": "my-resource-group2",
	// 					"type": "Microsoft.Resources/resourceGroups",
	// 					"apiVersion": "2019-03-01",
	// 					"id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group2",
	// 					"location": "{location3}",
	// 				},
	// 				ChangeType: to.Ptr(armresources.ChangeTypeCreate),
	// 				ResourceID: to.Ptr("/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group2"),
	// 		}},
	// 	},
	// 	Status: to.Ptr("succeeded"),
	// }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

JavaScript

const { ResourceManagementClient } = require("@azure/arm-resources");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to Returns changes that will be made by the deployment if executed at the scope of the subscription.
 *
 * @summary Returns changes that will be made by the deployment if executed at the scope of the subscription.
 * x-ms-original-file: specification/resources/resource-manager/Microsoft.Resources/stable/2021-04-01/examples/PostDeploymentWhatIfOnSubscription.json
 */
async function predictTemplateChangesAtSubscriptionScope() {
  const subscriptionId =
    process.env["RESOURCES_SUBSCRIPTION_ID"] || "00000000-0000-0000-0000-000000000001";
  const deploymentName = "my-deployment";
  const parameters = {
    location: "westus",
    properties: { mode: "Incremental", parameters: {}, templateLink: {} },
  };
  const credential = new DefaultAzureCredential();
  const client = new ResourceManagementClient(credential, subscriptionId);
  const result = await client.deployments.beginWhatIfAtSubscriptionScopeAndWait(
    deploymentName,
    parameters
  );
  console.log(result);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

dotnet

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Resources;
using Azure.ResourceManager.Resources.Models;

// Generated from example definition: specification/resources/resource-manager/Microsoft.Resources/stable/2021-04-01/examples/PostDeploymentWhatIfOnSubscription.json
// this example is just showing the usage of "Deployments_WhatIfAtSubscriptionScope" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this ArmDeploymentResource created on azure
// for more information of creating ArmDeploymentResource, please refer to the document of ArmDeploymentResource
string subscriptionId = "00000000-0000-0000-0000-000000000001";
string scope = $"/subscriptions/{subscriptionId}";
string deploymentName = "my-deployment";
ResourceIdentifier armDeploymentResourceId = ArmDeploymentResource.CreateResourceIdentifier(scope, deploymentName);
ArmDeploymentResource armDeployment = client.GetArmDeploymentResource(armDeploymentResourceId);

// invoke the operation
ArmDeploymentWhatIfContent content = new ArmDeploymentWhatIfContent(new ArmDeploymentWhatIfProperties(ArmDeploymentMode.Incremental)
{
    TemplateLink = null,
    Parameters = BinaryData.FromObjectAsJson(new Dictionary<string, object>()
    {
    }),
})
{
    Location = new AzureLocation("westus"),
};
ArmOperation<WhatIfOperationResult> lro = await armDeployment.WhatIfAsync(WaitUntil.Completed, content);
WhatIfOperationResult result = lro.Value;

Console.WriteLine($"Succeeded: {result}");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Sample response

Status code:

200

{
  "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"
          }
        }
      },
      {
        "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group2",
        "changeType": "Create",
        "after": {
          "apiVersion": "2019-03-01",
          "id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group2",
          "type": "Microsoft.Resources/resourceGroups",
          "name": "my-resource-group2",
          "location": "{location3}"
        }
      }
    ]
  }
}

Status code:

202

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

ParametersLink

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.

TemplateLink

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