New-AzureResourceGroup

Article
04/10/2014

New-AzureResourceGroup

Creates an Azure resource group and its resources

Syntax

Parameter Set: Default
New-AzureResourceGroup -Location <String> -Name <String> [-DeploymentName <String> ] [-Force] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via Gallery and template parameters file
New-AzureResourceGroup -GalleryTemplateIdentity <String> -Location <String> -Name <String> -TemplateParameterFile <String> [-DeploymentName <String> ] [-Force] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via Gallery and template parameters object
New-AzureResourceGroup -GalleryTemplateIdentity <String> -Location <String> -Name <String> -TemplateParameterObject <Hashtable> [-DeploymentName <String> ] [-Force] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via Gallery without parameters
New-AzureResourceGroup -GalleryTemplateIdentity <String> -Location <String> -Name <String> [-DeploymentName <String> ] [-Force] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template file and template parameters file
New-AzureResourceGroup -Location <String> -Name <String> -TemplateFile <String> -TemplateParameterFile <String> [-DeploymentName <String> ] [-Force] [-StorageAccountName <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

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

Parameter Set: Deployment via template file without parameters
New-AzureResourceGroup -Location <String> -Name <String> -TemplateFile <String> [-DeploymentName <String> ] [-Force] [-StorageAccountName <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template uri and template parameters file
New-AzureResourceGroup -Location <String> -Name <String> -TemplateParameterFile <String> -TemplateUri <String> [-DeploymentName <String> ] [-Force] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template uri and template parameters object
New-AzureResourceGroup -Location <String> -Name <String> -TemplateParameterObject <Hashtable> -TemplateUri <String> [-DeploymentName <String> ] [-Force] [-TemplateVersion <String> ] [ <CommonParameters>]

Parameter Set: Deployment via template uri without parameters
New-AzureResourceGroup -Location <String> -Name <String> -TemplateUri <String> [-DeploymentName <String> ] [-Force] [-TemplateVersion <String> ] [ <CommonParameters>]

Detailed Description

The New-AzureResourceGroup cmdlet creates an Azure resource group and its resources and returns an object that represents the resource group.

Use this cmdlet to create a new resource group. To add a deployment to an existing resource group, use the New-AzureResourceGroupDeployment cmdlet. To add a resource to an existing resource group, use the New-AzureResource cmdlet.

An Azure resource is a user-managed Azure entity, such as a database server, database, or web site. An Azure resource group is a collection of Azure resources that are deployed as a unit.

You can create a resource group with just a name and location, and then use the New-AzureResource cmdlet to create resources and add them to the resource group. However, typically, you use a resource group template, which is a JSON-based model 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 (Get-AzureResourceGroupGalleryTemplate) and you can create your own templates. Azure resource group templates are text files in JavaScript Object Notation (JSON) format.

To find a gallery template, use the Get-AzureResourceGroupGalleryTemplate template cmdlet. To use a gallery template, use the GalleryTemplateIdentity parameter of New-AzureResourceGroup 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

-DeploymentName<String>

Specifies the name of the deployment project for the resource group. Because the deployment properties are defined in a template, this parameter is valid only when you specify a template. This parameter is optional. The default value is the template name without the .json file name extension.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	True (ByPropertyName)
Accept Wildcard Characters?	false

-Force

Suppresses the confirmation prompt and overwrites an existing resource group with the same name. By default, New-AzureResourceGroup prompts for confirmation before replacing an existing resource group.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-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

-Location<String>

Specifies the location of the resource group. This parameter is required. Enter an Azure data center location, such as "West US" or "Southeast Asia".

You can place a resource group in any location. The resource group does not have to be in the same location your Azure subscription or the same location as its resources. Resource groups can contain resources from different locations. To determine which location support each resource type, use the Get-AzureLocation cmdlet.

Aliases	none
Required?	true
Position?	named
Default Value	none
Accept Pipeline Input?	True (ByPropertyName)
Accept Wildcard Characters?	false

-Name<String>

Specifies a name for the resource group. This parameter is required. The resource name must be unique in the subscription.

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

If a resource group with that name already exists, the command prompts you for confirmation before replacing the existing resource group. To suppress the confirmation prompt, use the Force parameter.

Aliases	ResourceGroupName
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-AzureResourceGroup 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.

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.

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-AzureResourceGroup 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.ResourceManagement.Models.PSResourceGroup

New-AzureResourceGroup returns an object that represents the resource group.

Notes

The New-AzureResourceGroup cmdlet is included in the Azure Resource Manager module beginning in module version 0.8.0.
If a resource group with this name already exists in the subscription, the cmdlet prompts you before replacing it. To suppress the confirmation prompt, use the Force parameter.

Examples

Example 1: Create an empty resource group

This command creates a resource group that has no resources. You can use the New-AzureResource or New-AzureResourceGroupDeployment cmdlets to add resources and deployments to this resource group.

PS C:\> New-AzureResourceGroup -Name RG1 -Location "South Central US"

ResourceGroupName : RG1
Location          : southcentralus
ProvisioningState : Succeeded
Resources

Example 2: Create a resource group from a custom template

This command creates the "ContosoHosting" resource group from a custom template. It uses the TemplateFile parameter to specify the path and file name of the ContosoHosting.json template file and the TemplateParameterFile parameter to specify the ContosoHostingParms.json file, which contains the names and values of the parameters in the template. Because the command does not specify a storage account, New-AzureResourceGroup uses the current storage account in the subscription.

PS C:\> New-AzureResourceGroup –Name ContosoHosting –Location "West US" –TemplateFile D:\Templates\ContosoHosting.json -TemplateVersion "2014-04-01-preview" -DeploymentName ContosoHosting -TemplateParameterFile D:\Templates\ContosoHostingParms.json

Name:     ContosoHosting
Location: westus
Resources: 
    Name             Type                         Location
    ===============  =======================      ========
    ContosoHosting   Microsoft.Web/serverFarms    westus
    Contoso          Microsoft.Web/Sites          West US

Example 3: Create a resource group from a gallery template

This example shows how to create a resource group 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-AzureResourceGroup cmdlet to create a new resource group. It uses the GalleryTemplateIdentity parameter to specify the identity of the gallery template. In this scenario, you don't need to save the gallery template to disk.

After you type the cmdlet parameters and values, 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-AzureResourceGroup –Name ContosoRG01 –Location "West US" –StorageAccountName contosostorage01 -GalleryTemplateIdentity Microsoft.WebSite.0.1.0-preview1 -siteName ContosoWeb -hostingPlanName ContosoHosting -siteMode Limited -computeMode Shared -siteLocation "South Central US" -subscriptionID "9b14a38b-4b93-4554-8bb0-3cefb47abcde" -resourceGroup ContosoRG01

ResourceGroupName : ContosoRG01
Location          : westus
ProvisioningState : Succeeded
Resources         : 
                    Name             Type                       Location
                    ===============  =========================  ==========
                    Default1         Microsoft.Web/serverFarms  southcentralus
                    ContosoWeb       Microsoft.Web/sites        southcentralus

Example 4: Create a resource group from a saved gallery template

This example shows how to create a resource group from a gallery template that you saved to disk by using the Save-AzureResourceGroupGalleryTemplate cmdlet and a hash table of template parameter names and values.

The first command uses the Get-AzureResourceGroupGalleryTemplate to get a gallery item. It pipes the gallery item to the Save-AzureResourceGroupGalleryTemplate cmdlet, which save the template as a JSON file in the path that you specify.

PS C:\> Get-AzureResourceGroupGalleryTemplate -Identity Microsoft.WebSite.0.1.0-preview1 | Save-AzureResourceGroupTemplate -Path D:\Azure\Templates

Path: 

D:\Azure\Templates\Microsoft.WebSite.0.1.0-preview1.json

Before we create the hash table of template parameters, we need to know which parameters the template requires. The second command uses the Get-Content cmdlet to get the contents of the template file and its Raw parameter, which ignores line breaks and returns a single JSON string. The command pipes the template to the ConvertFrom-Json cmdlet, which returns a custom object (PSCustomObject) that represents the template and saves it in the $t variable. You can use this technique to manipulate the template in Windows PowerShell.

PS C:\> $t = Get-Content -Raw -Path $home\Documents\Azure\Templates\Microsoft.WebSite.0.1.0-preview1.json | ConvertFrom-Json

The third command gets the Parameters property of the template custom object. The object also has a Resources property that represents the resources in the template.

PS C:\> $t.Parameters

siteName        : @{type=string}

hostingPlanName : @{type=string}

siteMode        : @{type=string}

computeMode     : @{type=string}

siteLocation    : @{type=string}

subscriptionId  : @{type=string}

resourceGroup   : @{type=string}

The fourth command creates a hash table of the template parameters and values and saves them in a $params variable.

PS C:\> $params = @{siteName="ContosoWeb"; hostingPlanName = "ContosoHosting"; siteMode = "Limited"; computeMode = "Shared"; siteLocation = "South Central US"; subscriptionId = "9b14a38b-4b93-4554-8bb0-3cefb47abcde"; resourceGroup = "ContosoRG01"}

The fifth command uses the New-AzureResourceGroup cmdlet to create the resource group. It uses the TemplateFile parameter to specify the gallery template file on disk and the TemplateParameterObject parameter to specify the hash table of template parameter names and values in the $params variable.

The cmdlet returns an object that represents the new resource group.

PS C:\> New-AzureResourceGroup –Name ContosoRG01 –Location "West US" –StorageAccountName contosostorage01 -DeploymentName WebDeploy01 -TemplateFile $home\Documents\Azure\Templates\Microsoft.WebSite.0.1.0-preview1.json -TemplateParameterObject @params

ResourceGroupName : ContosoRG01
Location          : westus
ProvisioningState : Succeeded
Resources         : 
                    Name             Type                       Location
                    ===============  =========================  ==========
                    Default1         Microsoft.Web/serverFarms  southcentralus
                    ContosoWeb       Microsoft.Web/sites        southcentralus

New-AzureResourceGroup