New-AzureResource

  • Article

New-AzureResource

Creates a new resource in a resource group

Syntax

Parameter Set: Default
New-AzureResource -ApiVersion <String> -Location <String> -Name <String> -ResourceGroupName <String> -ResourceType <String> [-Force] [-ParentResource <String> ] [-PropertyObject <Hashtable> ] [ <CommonParameters>]

Detailed Description

The New-AzureResource cmdlet creates an Azure resource, such as a website, SQL Azure database server, or SQL Azure database, in a new or existing resource group.

If a resource with the same name exists in the resource group, the cmdlet prompts for confirmation before replacing the existing resource. To suppress the confirmation prompt, use the Force parameter.

A resource is a user-managed Azure entity. A resource group is a collection of resources that are deployed as a unit. Every resource belongs to exactly one resource group.

Typically, you use a template to create a resource group (New-AzureResourceGroup) and its resources. Then, if necessary, you can use this cmdlet to add additional resources to it.

Parameters

-ApiVersion<String>

Specifies the API version that is supported by the resource provider. This parameter is required.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-Force

Overwrites an existing resource group without warning. This parameter suppresses the confirmation prompt that New-AzureResource displays by default when the resource group already contains a resource with the same resource name.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Location<String>

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

You can place a resource in any location that supports resources of that type. The resource does not have to be in the same location your Azure subscription or the same location as its resource group. Resource groups can contain resources from different locations. To determine which locations 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 a resource. This parameter is required.

The resource name must be unique in the resource group. If the name of a particular type of resource must be unique in a larger scope, the command will fail with an message that the name is not unique in the required scope.

Aliases

ResourceName

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-ParentResource<String>

Specifies the names of the logical parent of a resource. This parameter is optional. Enter the fully qualified name of the parent resource, such as "Microsoft.Sql/servers/ContosoSQLSvr". The name is case-sensitive. Wildcards are not permitted.

Use this parameter when the resource is a type that has parents. For example, every SQL Azure database is associated with a SQL Azure database server. A resource group is not a parent of its resources.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-PropertyObject<Hashtable>

Specifies properties values for the properties of a resource. Enter a hash table in @{propertyName = propertyValue} format. This parameter is optional.

Use this parameter to specify the values of properties that are specific to a resource type. To find the properties that you can set for each type of resource, look at a few gallery templates, such as the templates that the Get-AzureResourceGroupGalleryTemplate cmdlet returns.

For more information about hash tables in Windows PowerShell, type: Get-Help about_Hash_Tables (https://go.microsoft.com/fwlink/?LinkID=324844).

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-ResourceGroupName<String>

Specifies the resource group for this resource. This parameter is required. Enter the name of a new or existing resource group. If the resource group doesn't exist, this cmdlet creates it for you.

A resource group is a collection of resources that are deployed as a unit. Every resource belongs to exactly one resource group.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-ResourceType<String>

Enter the type of the resource that you are creating, such as "Microsoft.Web/sites" or " Microsoft.Sql/servers/databases". This parameter is required and its value is case-sensitive. Wildcards are not permitted.

Aliases

none

Required?

true

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

    The cmdlet returns a PSResource object that represents the new resource.

Notes

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

  • When you add a resource to a resource group, Azure Resource Manager also adds to the resource group any resource that you need to support the new resource.

  • If you encounter the "Conflict: Not enough available reserved instance servers to satisfy this request" error, wait a few minutes and try the command again. If the request is automated, set it to retry repeatedly at random intervals. You can also try a different location for the resource. To find locations that support resources of a particular type, use the Get-AzureLocation cmdlet.

Examples

Example 1: Create a new web site

This command uses the New-AzureResource cmdlet to create the ContosoEngSite web site in the ContosoEngineering resource group. If the ContosoEngineering resource group doesn't exist, New-AzureResource creates it. If the ContosoEngineering resource group already has a resource named ContosoEngSite, the cmdlet prompt for confirmation before replacing it.

The command uses the Location parameter to place the new web in the "North Europe" data center, although the resource group and its resources are located in several different locations.

The cmdlet returns a PSResource object that represents the new database.

PS C:\> New-AzureResource -Name ContosoEngSite -Location "North Europe" -ResourceGroupName ContosoEngineering -ResourceType "Microsoft.Web/sites" -ApiVersion 2004-04-01 -PropertyObject @{"name" = "ContosoEngSite"; "siteMode" = "Limited"; "computeMode" = "Shared"} 

Name              : ContosoEngSite
ResourceGroupName : ContosoEngineering
ResourceType      : Microsoft.Web/sites
Location          : North Europe
Properties        : {[name, ContosoEngSite], [state, Running], [hostNames, 
                    System.Collections.Generic.List`1[System.Object]], [webSpace, 
                    ContosoEngineering-NorthEuropewebspace]...}

Example 2: Create a web site with property values

These commands create the ContosoWeb Azure website in the CRG01 resource group.

The first command creates a hash table of web site properties and saves it in the $WebsiteProperties variable. To find the properties that you can set for an Azure web site, use a gallery template, such as the ones that the Get-AzureResourceGroupGalleryTemplate cmdlet return.

The second command uses the New-AzureResource cmdlet to create the web site. The value of the PropertyObject parameter is the hash table in the $WebsiteProperties variable.

PS C:\> $WebsiteProperties = @{name = "ContosoWeb"; serverFarm = CS01; computeMode = "Shared"; siteMode = "Limited";}

PS C:\>New-AzureResource -Name ContosoWeb -ResouceGroupName CRG01 -ResourceType 'Microsoft.Web/sites' -Location "South Central US" -ApiVersion 2014-04-01 -PropertyObject $WebsiteProperties

Name              : ContosoWeb
ResourceGroupName : ContosoEngineering
ResourceType      : Microsoft.Web/sites
Location          : South Central US
Properties        : {[name, ContosoWeb], [state, Running], [hostNames, 
                    System.Collections.Generic.List`1[System.Object]], [webSpace, 
                   CRG01-Southcentralwebspace]...}

Example 3: Add a website to a resource group

This example shows a typical use of this cmdlet. The first command uses the New-AzureResourceGroup cmdlet to create the ContosoPortal resource group. The command uses the WordPress gallery template (Get-AzureResourceGroupGalleryTemplate) and a JSON file, WordPressParameters.json, to specify values for the template-specific parameters, such as the name and location of the database, a name for the hosting plan, and web deployment credentials.

The second command uses the New-AzureResource cmdlet to add an additional database to the ContosoPortal resource group. The command uses the PropertyObject parameter to specify a hash table of values for the Edition and MaxSizeGB properties of the new database. For the other databases in the resource group, these values were specified in the PortalParameters.rgcfg resource group configuration file.

PS C:\> New-AzureResourceGroup -Name ContosoPortal -Location "West US" -GalleryTemplateIdentity WordPress.WordPress.0.1.0-preview1 -TemplateParameterFile ".\WordPressParameters.json"

PS C:\>New-AzureResource –Name sqldb03 –ResourceType "Microsoft.Sql/servers/databases" –ResourceGroup ContosoPortal –Location "West US" –ParentResourceName "Microsoft.Sql/servers/ContosoServer01" –PropertyObject @{Edition = "Enterprise"; MaxSizeGB = 100}