New-AzureResourceGroupDeployment

  • Article

New-AzureResourceGroupDeployment

Add an Azure deployment to a resource group.

Syntax

Parameter Set: Default
New-AzureResourceGroupDeployment -ResourceGroupName <String> [-Name <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via Gallery and template parameters file
New-AzureResourceGroupDeployment -GalleryTemplateIdentity <String> -ResourceGroupName <String> -TemplateParameterFile <String> [-Name <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via Gallery and template parameters object
New-AzureResourceGroupDeployment -GalleryTemplateIdentity <String> -ResourceGroupName <String> -TemplateParameterObject <Hashtable> [-Name <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via Gallery without parameters
New-AzureResourceGroupDeployment -GalleryTemplateIdentity <String> -ResourceGroupName <String> [-Name <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template file and template parameters file
New-AzureResourceGroupDeployment -ResourceGroupName <String> -TemplateFile <String> -TemplateParameterFile <String> [-Name <String> ] [-StorageAccountName <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template file and template parameters object
New-AzureResourceGroupDeployment -ResourceGroupName <String> -TemplateFile <String> -TemplateParameterObject <Hashtable> [-Name <String> ] [-StorageAccountName <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template file without parameters
New-AzureResourceGroupDeployment -ResourceGroupName <String> -TemplateFile <String> [-Name <String> ] [-StorageAccountName <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template uri and template parameters file
New-AzureResourceGroupDeployment -ResourceGroupName <String> -TemplateParameterFile <String> -TemplateUri <String> [-Name <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template uri and template parameters object
New-AzureResourceGroupDeployment -ResourceGroupName <String> -TemplateParameterObject <Hashtable> -TemplateUri <String> [-Name <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template uri without parameters
New-AzureResourceGroupDeployment -ResourceGroupName <String> -TemplateUri <String> [-Name <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Detailed Description

The New-AzureResourceGroupDeployment cmdlet adds a deployment to an existing resource group, including the resources that the deployment needs. This cmdlet is similar to the New-AzureResourceGroup cmdlet, but it works on existing resource groups, instead of new ones. To add a single resource to a resource group, use the New-AzureResource cmdlet.

An Azure resource is a user-managed Azure entity, such as a database server, database, website, virtual machine, or storage account. An Azure resource group is a collection of Azure resources that are deployed as a unit, such as the web site, database server, and databases that are required for a financial web site. A deployment is the operation that makes the resources in the resource group available for use.

To add a resource group deployment, specify the name of an existing resource group and a resource group template, which is a JSON string that represents of a resource group for a complex cloud-based service, such as a web portal. The template includes parameter (placeholders) for required resources and configurable property values, likes names and sizes. You can find many templates in the Azure template gallery and you can create your own templates.

To find a gallery template, use the Get-AzureResourceGroupGalleryTemplate template cmdlet. To use a gallery template, use the GalleryTemplateIdentity parameter of New-AzureResourceGroupDeployment to specify the template identity. Or, use the Save-AzureResourceGalleryTemplate cmdlet to save the gallery template as a JSON file, and then use the TemplateFile or TemplateUri parameters to provide the name and location of the file.

You can also create a custom resource group template, either by typing in a text file or by editing a gallery template. To use a custom template to create a resource group, use TemplateFile or TemplateUri parameters to supply the location and file name.

Each template has different parameters for configurable properties. To specify values for the template parameters, use a JSON-formatted parameter file (TemplateParameterFile parameter) or a hash table of parameter names and values (TemplateParameterObject parameter). Also, the template parameters are added to the command dynamically as soon as you specify a template. To use the dynamic parameters, just type them in the command, or type a minus sign to indicate a parameter name (-) and then press the TAB key repeatedly to cycle through the available parameters. If you miss a required parameter, the cmdlet prompts you for the value.

Parameters

-GalleryTemplateIdentity<String>

Specifies the identity of a template in the Azure gallery. To find gallery templates, use the Get-AzureResourceGroupGalleryTemplate cmdlet. The value of the Identity property of each gallery item is displayed by default.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-Name<String>

Specifies the name of the deployment project for the resource group. Use -Name or its alias -DeploymentName. This parameter is optional. The default value is the template name without the .json file name extension.

Aliases

DeploymentName

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-ResourceGroupName<String>

Specifies the name of the resource group to which this deployment is added. This parameter is required. If the resource group does not exist, the command fails.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-StorageAccountName<String>

Specifies the name of a storage account in the subscription. New-AzureResourceGroupDeployment saves the contents of template files in the storage account. This parameter is optional, but a storage account is required when you use the TemplateFile parameter.

The default value is the current storage account in the subscription. If you do not specify a storage account and the subscription does not have a current storage account, the command fails.

To create a storage account, use the Switch-AzureMode cmdlet to switch to the Azure module, and then use the New-AzureStorageAccount cmdlet. To make the a storage account the "current storage account" for the subscription, use the CurrentStorageAccountName parameter of the Set-AzureSubscription cmdlet.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-TemplateFile<String>

Specifies the path and file name of a JSON template file on disk. This can be a custom template or a gallery template that is saved to disk as a JSON file, such as by using the Save-AzureResourceGroupGalleryTemplate cmdlet.

To use this parameter, the subscription must include a storage account where the cmdlet can save the template. By default, this cmdlet uses the current storage account in the subscription, but you can use the StorageAccountName parameter to specify an alternate storage account. If you do not specify a storage account and the subscription does not have a storage account that is designated as "current," the command fails.

To create a storage account, use the Switch-AzureMode cmdlet to switch to the Azure module, and then use the New-AzureStorageAccount cmdlet. To make the a storage account the "current storage account" for the subscription, use the CurrentStorageAccountName parameter of the Set-AzureSubscription cmdlet.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-TemplateParameterFile<String>

Specifies the path and name of a JSON file with the names and values of the template parameters. This parameter is optional.

If a template has parameters, you must specify parameter values, but you can use this parameter or the TemplateParameterObject parameter. Also, the template parameters are added to the command dynamically when you specify a template. To use the dynamic parameters, just type them in the command, or type a minus sign to indicate a parameter name (-) and then press the TAB key repeatedly to cycle through the available parameters. If you miss a required parameter, the cmdlet prompts you for the value.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-TemplateParameterObject<Hashtable>

Specifies a hash table of template parameter names and values. This parameter is optional. For help with hash tables in Windows PowerShell, type: Get-Help about_Hash_Tables.

If a template has parameters, you must specify parameter values, but you can use this parameter or the TemplateParameterObject parameter. Also, the template parameters are added to the command dynamically when you specify a template. To use the dynamic parameters, just type them in the command, or type a minus sign to indicate a parameter name (-) and then press the TAB key repeatedly to cycle through the available parameters. If you miss a required parameter, the cmdlet prompts you for the value.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-TemplateUri<String>

Specifies the URI of a JSON template file. This file can be a custom template or a gallery template that is saved as a JSON file, such as by using the Save-AzureResourceGroupGalleryTemplate cmdlet.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-TemplateVersion<String>

Specifies a particular version of the gallery or custom template. Enter the version number, such as "2014-04-01-preview". This parameter is optional. If you specify this parameter, New-AzureResourceGroupDeployment verifies that the specified template has the matching version and fails if it does not.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

<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.

  • Microsoft.Azure.Commands.ResourceManager.Models.PSResourceGroupDeployment

Notes

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

Examples

This example shows how to create a resource group deployment from a gallery template and use the parameters that are added to the command dynamically to provide the template parameter values.

This command uses the New-AzureResourceGroupDeployment cmdlet to create a new deployment in the ContosoRG01 resource group. It uses the GalleryTemplateIdentity parameter to specify the gallery template. In this scenario, you don't need to save the gallery template to disk.

Instead of using a template parameter file or a template parameter object, we'll just use the parameters that are added to the command dynamically when you specify the template.

After typing the Name parameter and its value, type a minus sign (to indicate a parameter name) and then press the TAB key to trigger tab-completion. The cmdlet adds a parameter, such as siteMode. Type the parameter value, type a minus sign, press TAB, and it adds another parameter. To cycle through the parameter names, press TAB repeatedly. If you miss a mandatory template parameter, the cmdlet prompts you for the value.

PS C:\> New-AzureResourceGroupDeployment -New-AzureResourceGroupDeployment -ResourceGroupName ContosoRG01 -GalleryTemplateIdentity Microsoft.WebSite.0.1.0-preview1 -Name WebDeploy01 -siteName ContosoWeb -hostingPlanName ContosoHosting -siteMode Limited -computeMode Dedicated -siteLocation "North Europe" -subscriptionID "9b14a38b-4b93-4554-8bb0-3cefb47abcde" -resourceGroup ContosoRG01

DeploymentName    : WebDeploy01

ResourceGroupName : ContosoRG01

ProvisioningState : Succeeded

Timestamp         : 3/26/2014 1:56:55 AM

Mode              : Incremental

TemplateLink      : 

                    Uri            : https://gallerystoreprodch.blob.core.windows.net/prod-microsoft-

                    ContentVersion : 1.0.0.0



Parameters        : 

                    Name             Type                       Value

                    ===============  =========================  ==========

                    siteName         String                     ContosoWeb

                    hostingPlanName  String                     ContosoHosting

                    siteMode         String                     Limited

                    computeMode      String                     Dedicated

                    siteLocation     String                     North Europe

                    subscriptionId   String                     9b14a38b-4b93-4554-8bb0-3cefb47abcde

                    resourceGroup    String                     ContosoRG01

Example 2: Use a custom template and parameter file

This command creates a new deployment by using a custom template and a template file on disk. The command uses the TemplateFile parameter to specify the template and the TemplateParameterFile to specify a file of parameters and parameter values. It uses the TemplateVersion parameter to specify a particular version of the template. Because the template files are stored in a storage account of the subscription, the cmdlet uses the StorageAccountName to specify the storage account to use.

PS C:\> New-AzureResourceGroupDeployment -ResourceGroupName ContosoEngineering -TemplateFile D:\Azure\Templates\EngineeringSite.json -TemplateParameterFile D:\Azure\Templates\EngSiteParms.json -TemplateVersion "2.1" -StorageAccountName contosostorage

This command creates a new deployment by using a gallery template that is saved to disk as a JSON file and a hash table of parameter values.

The first command uses the Save-AzureResourceGroupGalleryTemplate cmdlet to save the WordPress gallery template as a JSON file on disk.

PS C:\> Save-AzureResourceGroupGalleryTemplate -Identity WordPress.WordPress.0.1.0-preview1 -Path D:\Azure\Templates

Path: 

D:\Azure\Templates\WordPress.WordPress.0.1.0-preview1.json

The second command saves a hash table of the template parameter values in the $params variable.

PS C:\> $params = @{siteName="ContosoBlog";hostingPlanName="ContosoHosting";siteMode="Limited";computeMode="Shared";siteLocation="North Europe";sku="Shared";workerSize="0";databaseName=contosodb1;databaseLocation="South Central US";databaseSku="Free";subscriptionId="7363c612-d678-4171-a715-585c237abcde";resourceGroup="ContosoRG01";dbSubscriptionId="7363c612-d678-4171-a715-585c237abcde";dbResourceGroup="ContosoRG01"}

The third command uses New-AzureResourceGroupDeployment cmdlet to add the new deployment to the ContosoRG01 resource group.

The command uses the TemplateFile parameter to specify the saved gallery template file and the TemplateParameterObject to specify the hash table of parameters and parameter values in the $params variable. Because the template files are stored in a storage account of the subscription, the cmdlet uses the StorageAccountName to specify the storage account to use.

PS C:\> New-AzureResourceGroupDeployment -ResourceGroupName ContosoRG01 -TemplateFile D:\Azure\Templates\WordPress.WordPress.0.1.0-preview1.json -TemplateParameterObject $params -StorageAccountName contosostorage