New-AzureResource
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> ] [-Profile <Microsoft.Azure.Common.Authentication.Models.AzureProfile> ] [-PropertyObject <Hashtable> ] [-Tag <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 |
-Profile<Microsoft.Azure.Common.Authentication.Models.AzureProfile>
Specifies the Azure profile from which this cmdlet reads. If you do not specify a profile, this cmdlet reads from the local default profile.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
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>
Specifies 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 |
-Tag<Hashtable[]>
Applies the specified tags to the new resource. Enter new tags or predefined tags that you created by using the New-AzureTag 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-AzureResource and Get-AzureResourceGroup 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-AzureTag cmdlet.
The Tag parameter is added in version 0.8.5 of the AzureResourceManager module.
Aliases |
Tags |
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 (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.
New-AzureResource -Name ContosoEngSite -Location "North Europe" -ResourceGroupName ContosoEngineering -ResourceType "Microsoft.Web/sites" -ApiVersion 2015-04-01 -PropertyObject @{"name" = "ContosoEngSite"; "siteMode" = "Limited"; "computeMode" = "Shared"}
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.
$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 2015-04-01 -PropertyObject $WebsiteProperties
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.
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" -ParentResource "Microsoft.Sql/servers/ContosoServer01" -PropertyObject @{Edition = "Enterprise"; MaxSizeGB = 100}
Example 4: Create a resource group with tags
This command creates a new website and applies two tags to it. The command uses the Tag parameter to apply a "Status" tag with a value of "Approved" and a tag named "New" with no value.
The Tag parameter is introduced in version 0.8.5 of the AzureResourceManager module.
New-AzureResource -Name ContosoEngSite -Location "North Europe" -ResourceGroupName ContosoEngineering -ResourceType "Microsoft.Web/sites" -ApiVersion 2015-04-01 -Tag @{Name="Status";Value="Approved"},@{Name="New"}