Stop-AzureResourceGroupDeployment

Stop-AzureResourceGroupDeployment

Cancels a resource group deployment

Syntax

Parameter Set: Default
Stop-AzureResourceGroupDeployment [-ResourceGroupName] <String> [[-Name] <String> ] [[-Force]] [[-PassThru]] [ <CommonParameters>]

Detailed Description

The Stop-AzureResourceGroupDeployment cmdlet cancels an Azure resource group deployment that is started, but not completed. To stop a deployment, the deployment must have an incomplete provisioning state, such as Provisioning, and not a completed state, such as Provisioned or Failed.

An Azure resource is a user-managed entity, such as a website, database, or database server. A resource group is a collection of resources that are deployed as a unit. To deploy a resource group, use the New-AzureResourceGroup or New-AzureResourceGroupDeployment cmdlets. The New-AzureResource cmdlet creates a new resource, but it does not trigger a resource group deployment operation that this cmdlet can stop.

This cmdlet stops only one running deployment. Use the Name parameter to stop a particular deployment. If you omit the Name parameter, Stop-AzureResourceGroupDeployment searches for a running deployment and stops it, but if it finds more than one running deployment, the command fails.

By default, Stop-AzureResourceGroupDeployment prompts you for confirmation. To suppress the prompt, use the Force parameter.

Parameters

-Force

Suppresses the confirmation prompt. By default, Stop-AzureResourceGroupDeployment prompts you before stopping a deployment.

-Name<String>

Stops the specified deployment. Enter the deployment name. This parameter is optional.

Without this parameter, Stop-AzureResourceGroupDeployment searches for a running deployment in the resource group and stops it, but if it finds more than one running deployment, the command fails.

You can use -Name or its alias, -DeploymentName.

To find the deployment name, use the Get-AzureResourceGroupDeployment cmdlet.

-PassThru

Returns $True when the stopping operation succeeds and $False when it fails. By default, this cmdlet does not generate any output.

-ResourceGroupName<String>

Stops the deployment of the specified resource group. This parameter is required.

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (https://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

• None

  You can pipe input to this cmdlet by property name, but not by value.

Outputs

The output type is the type of the objects that the cmdlet emits.

• None or Boolean

  If you use the Passthru parameter, this cmdlet returns a Boolean value that represents the success or failure of the operation. Otherwise, this cmdlet does not return any output.

Notes

• The Stop-AzureResourceGroupDeployment cmdlet is included in the Azure Resource Manager module beginning in module version 0.8.0.

Examples

Example 1: Stop a resource group deployment

This example shows how to use the Stop-AzureResourceGroupDeployment command to stop a deployment in progress. The first command uses the New-AzureResourceGroup cmdlet to create and deploy a new resource group.

Immediately after pressing enter, you remember that you need to get manager approval before deploying new resources. The second command uses the Stop-AzureResourceGroupDeployment cmdlet to stop the deployment before it completes. The command uses the ResourceGroupName parameter to identify the deployment. It also uses the Force parameter to suppress the confirmation prompt.

PS C:\> New-AzureResourceGroup -ResourceGroupName ContosoRG01 -GalleryTemplateName WebHosting -TemplateParameterFile .\HostingTemplateValues
 
PS C:\>Stop-AzureResourceGroupDeployment -ResourceGroupName ContosoRG01 -Force

Example 2: Stop a resource group deployment by deployment name

This example shows how to use the Name (alias DeploymentName) parameter of the Stop-AzureResourceGroupDeployment command to stop a deployment in progress.

The first command uses the New-AzureResourceGroup cmdlet to create and deploy a new "ContosoRG01" resource group with a "DeployHost" deployment. The second command uses the New-AzureResourceGroupDeployment to add the "DeployPortal" deployment to the "ContosoRG01" resource group.

The third command uses the Stop-AzureResourceGroupDeployment cmdlet to stop the "DeployPortal" deployment before it completes. The command uses the ResourceGroupName parameter to identify the resource group and the Name parameter to specify the deployment name. Because the command include the Passthru parameter, the cmdlet returns a value of True ($True) to indicate that the deployment stopped.

PS C:\> New-AzureResourceGroup -ResourceGroupName ContosoRG01 -GalleryTemplateName WebHosting -TemplateParameterFile .\HostingTemplateValues -DeploymentName DeployHost
 
PS C:\>New-AzureResourceGroupDeployment -ResourceGroupName ContosoRG01 -TemplateParameterFile .\PortalTemplateValues -GalleryTemplateName WebPortal -DeploymentName DeployPortal

PS C:\>Stop-AzureResourceGroupDeployment -ResourceGroupName ContosoRG01 -Name DeployPortal -Passthru

True