New-AzureRmResourceGroup

Article
10/07/2015

New-AzureRmResourceGroup

Creates an Azure resource group and its resources

Syntax

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

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

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

Parameter Set: Deployment via Gallery and template parameters uri
New-AzureRmResourceGroup -GalleryTemplateIdentity <String> -Location <String> -Name <String> -TemplateParameterUri <String> [-DeploymentName <String> ] [-Force] [-Tag <Hashtable[]> ] [-TemplateVersion <String> ] [ <CommonParameters>]

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

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

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

Parameter Set: Deployment via template file template parameters uri
New-AzureRmResourceGroup -Location <String> -Name <String> -TemplateFile <String> -TemplateParameterUri <String> [-DeploymentName <String> ] [-Force] [-StorageAccountName <String> ] [-Tag <Hashtable[]> ] [-TemplateVersion <String> ] [ <CommonParameters>]

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

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

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

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

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

Detailed Description

This is the Description section

The New-AzureRmResourceGroup 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-AzureRmResourceGroupDeployment cmdlet. To add a resource to an existing resource group, use the New-AzureRmResource 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-AzureRmResource 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. You can find many templates in the Azure template gallery (Get-AzureRmResourceGroupGalleryTemplate) and you can create your own templates.To find a gallery template, use the Get-AzureRmResourceGroupGalleryTemplate template cmdlet. To use a gallery template, use the GalleryTemplateIdentity parameter of New-AzureRmResourceGroup to specify the template identity. Or, use the Save-AzureRmResourceGalleryTemplate 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.The template includes parameters (placeholders) for configurable property values, likes names and sizes. 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). Or, you can use the template parameters that 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 template parameter, the cmdlet prompts you for the value. Template parameter values that you specify at the command line take precedence over template parameter values in a template parameter object or file.

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-AzureRmResourceGroup 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-AzureRmResourceGroupGalleryTemplate 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-AzureRmLocation 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-AzureRmResourceGroup 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 a Switch-AzureMode -Name AzureServiceManagement command to switch to the Azure module, and then use the New-AzureRmStorageAccount cmdlet. To make the a storage account the "current storage account" for the subscription, use the CurrentStorageAccountName parameter of the Set-AzureRmSubscription cmdlet.

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

-Tag<Hashtable[]>

Applies the specified tags to the new resource group. Enter new tags or predefined tags that you created by using the New-AzureRmTag cmdlet.A "tag" is a name-value pair that you can apply to resources and resource groups. Use tags to categorize your resources, such as by department or cost center, or to track notes or comments about the resources. After you assign tags to resources, you can use the Tag parameters of Get-AzureRmResource and Get-AzureRmResourceGroup to search for resources and groups by tag name or name and value.Every tag must have a Name key. It can also have an optional Value key with one value. To specify a new tag, use a hash table, such as @{Name="FY2015"} or @{Name="Department";Value="IT"}. To specify multiple tags, use commas to separate the hash tables, such as -Tag @{Name="FY2015"}, @{Name="Department";Value="IT"}. To get your predefined tags, use the Get-AzureRmTag cmdlet.

Aliases	Tags
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-AzureRmResourceGroupGalleryTemplate 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-AzureRmStorageAccount cmdlet. To make the a storage account the "current storage account" for the subscription, use the CurrentStorageAccountName parameter of the Set-AzureRmSubscription 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 the TemplateParameterObject or the TemplateParameterFile parameters. Or, you can use 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. For help with hash tables in Windows PowerShell, type: Get-Help about_Hash_Tables.This parameter is optional. If a template has parameters, you must specify parameter values, but you can use the TemplateParameterObject or the TemplateParameterFile parameters. Or, you can use 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

-TemplateParameterUri<String>

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-AzureRmResourceGroupGalleryTemplate 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-AzureRmResourceGroup 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: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

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

None

Outputs

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

Microsoft.Azure.Commands.ResourceManagement.Models.PSResourceGroup

Examples

-------------------------- Example 1: Create an empty resource group --------------------------

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

PS C:\>New-AzureRmResourceGroup -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-AzureRmResourceGroup uses the current storage account in the subscription.

PS C:\>New-AzureRmResourceGroup ?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-AzureRmResourceGroup 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-AzureRmResourceGroup ?Name ContosoRG01 ?Location "West US" ?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-AzureRmResourceGroupGalleryTemplate cmdlet and a hash table of template parameter names and values.

PS C:\> The first command uses the Get-AzureRmResourceGroupGalleryTemplate to get a gallery item. It pipes the gallery item to the Save-AzureRmResourceGroupGalleryTemplate cmdlet, which save the template as a JSON file in the path that you specify.
PS C:\>Get-AzureRmResourceGroupGalleryTemplate -Identity Microsoft.WebSite.0.1.0-preview1 | Save-AzureRmResourceGroupTemplate -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-AzureRmResourceGroup 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. It uses the StorageAccountName parameter to specify the storage account in which the template is stored. You must specify a storage account when you use the TemplateFile parameter and a "current" storage account has not been selected for the subscription.The cmdlet returns an object that represents the new resource group.
PS C:\>New-AzureRmResourceGroup ?Name ContosoRG01 ?Location "West US" ?StorageAccountName contosostorage01 -DeploymentName WebDeploy01 -TemplateFile $home\Documents\Azure\Templates\Microsoft.WebSite.0.1.0-preview1.json -TemplateParameterObject @params -StorageAccountName ContosoStorage
ResourceGroupName : ContosoRG01
Location          : westus
ProvisioningState : Succeeded
Resources         : 
                    Name             Type                       Location
                    ===============  =========================  ==========
                    Default1         Microsoft.Web/serverFarms  southcentralus
                    ContosoWeb       Microsoft.Web/sites        southcentralus

-------------------------- Example 5: Create a resource group with tags --------------------------

This command creates a new empty resource group. This command is the same as the command in Example 1, except that it assigns tags to the resource group. The first tag, named "Empty," could be used to identify resource groups that have no resources. The second tag is named "Department" and has a value of "Marketing". You can use a tag like this one to categorize resource groups for administration or budgeting.

PS C:\>New-AzureRmResourceGroup -Name RG1 -Location "South Central US" -Tag @{Name="Empty"}, @{Name="Department";Value="Marketing"}

Share via

New-AzureRmResourceGroup