Create and modify an ExpressRoute circuit using PowerShell

This article helps you create an ExpressRoute circuit using PowerShell cmdlets and the Azure Resource Manager deployment model. You can also check the status, update, delete, or deprovision a circuit.

Before you begin

Before you begin, review the prerequisites and workflows before you begin configuration.

Working with Azure PowerShell

This article uses PowerShell cmdlets. To run the cmdlets, you can use Azure Cloud Shell, a free interactive shell. It has common Azure tools preinstalled and configured to use with your account. Just click the Copy to copy the code, paste it into the Cloud Shell, and then press enter to run it. There are a few ways to launch the Cloud Shell:

Click Try It in the upper right corner of a code block. Cloud Shell in this article
Open Cloud Shell in your browser. https://shell.azure.com/powershell
Click the Cloud Shell button on the menu in the upper right of the Azure portal. Cloud Shell in the portal

If you don't want to use Azure Cloud Shell, you can install PowerShell locally instead. If you choose to install and use PowerShell locally, be sure to install the latest version of the Azure Resource Manager PowerShell cmdlets. PowerShell cmdlets are updated frequently and you typically need to update your PowerShell cmdlets to get the latest feature functionality. If you don't update your PowerShell cmdlets, the values specify may fail.

To find the version of PowerShell that you are running locally, use the 'Get-Module -ListAvailable AzureRM' cmdlet. If you need to upgrade, see Install the Azure PowerShell module. For more information, see How to install and configure Azure PowerShell.

Create and provision an ExpressRoute circuit

1. Sign in to your Azure account and select your subscription

To begin your configuration, sign in to your Azure account. Use the following examples to help you connect:

If you are using Azure CloudShell, you don't need to run Connect-AzureRmAccount, as you will connect automatically.

Connect-AzureRmAccount

Check the subscriptions for the account:

Get-AzureRmSubscription

Select the subscription that you want to create an ExpressRoute circuit for:

Select-AzureRmSubscription -SubscriptionId "<subscription ID>"

2. Get the list of supported providers, locations, and bandwidths

Before you create an ExpressRoute circuit, you need the list of supported connectivity providers, locations, and bandwidth options.

The PowerShell cmdlet Get-AzureRmExpressRouteServiceProvider returns this information, which you’ll use in later steps:

Get-AzureRmExpressRouteServiceProvider

Check to see if your connectivity provider is listed there. Make a note of the following information, which you need later when you create a circuit:

  • Name
  • PeeringLocations
  • BandwidthsOffered

You're now ready to create an ExpressRoute circuit.

3. Create an ExpressRoute circuit

If you don't already have a resource group, you must create one before you create your ExpressRoute circuit. You can do so by running the following command:

New-AzureRmResourceGroup -Name "ExpressRouteResourceGroup" -Location "West US"

The following example shows how to create a 200-Mbps ExpressRoute circuit through Equinix in Silicon Valley. If you're using a different provider and different settings, substitute that information when you make your request. Use the following example to request a new service key:

New-AzureRmExpressRouteCircuit -Name "ExpressRouteARMCircuit" -ResourceGroupName "ExpressRouteResourceGroup" -Location "West US" -SkuTier Standard -SkuFamily MeteredData -ServiceProviderName "Equinix" -PeeringLocation "Silicon Valley" -BandwidthInMbps 200

Make sure that you specify the correct SKU tier and SKU family:

  • SKU tier determines whether an ExpressRoute standard or an ExpressRoute premium add-on is enabled. You can specify Standard to get the standard SKU or Premium for the premium add-on.
  • SKU family determines the billing type. You can specify Metereddata for a metered data plan and Unlimiteddata for an unlimited data plan. You can change the billing type from Metereddata to Unlimiteddata, but you can't change the type from Unlimiteddata to Metereddata.

Important

Your ExpressRoute circuit is billed from the moment a service key is issued. Ensure that you perform this operation when the connectivity provider is ready to provision the circuit.

The response contains the service key. You can get detailed descriptions of all the parameters by running the following command:

get-help New-AzureRmExpressRouteCircuit -detailed

4. List all ExpressRoute circuits

To get a list of all the ExpressRoute circuits that you created, run the Get-AzureRmExpressRouteCircuit command:

Get-AzureRmExpressRouteCircuit -Name "ExpressRouteARMCircuit" -ResourceGroupName "ExpressRouteResourceGroup"

The response looks similar to the following example:

Name                             : ExpressRouteARMCircuit
ResourceGroupName                : ExpressRouteResourceGroup
Location                         : westus
Id                               : /subscriptions/***************************/resourceGroups/ExpressRouteResourceGroup/providers/Microsoft.Network/expressRouteCircuits/ExpressRouteARMCircuit
Etag                             : W/"################################"
ProvisioningState                : Succeeded
Sku                              : {
                                     "Name": "Standard_MeteredData",
                                     "Tier": "Standard",
                                     "Family": "MeteredData"
                                      }
CircuitProvisioningState          : Enabled
ServiceProviderProvisioningState  : NotProvisioned
ServiceProviderNotes              :
ServiceProviderProperties         : {
                                      "ServiceProviderName": "Equinix",
                                      "PeeringLocation": "Silicon Valley",
                                      "BandwidthInMbps": 200
                                    }
ServiceKey                        : **************************************
Peerings                          : []

You can retrieve this information at any time by using the Get-AzureRmExpressRouteCircuit cmdlet. Making the call with no parameters lists all the circuits. Your service key is listed in the ServiceKey field:

Get-AzureRmExpressRouteCircuit

The response looks similar to the following example:

Name                             : ExpressRouteARMCircuit
ResourceGroupName                : ExpressRouteResourceGroup
Location                         : westus
Id                               : /subscriptions/***************************/resourceGroups/ExpressRouteResourceGroup/providers/Microsoft.Network/expressRouteCircuits/ExpressRouteARMCircuit
Etag                             : W/"################################"
ProvisioningState                : Succeeded
Sku                              : {
                                     "Name": "Standard_MeteredData",
                                     "Tier": "Standard",
                                     "Family": "MeteredData"
                                      }
CircuitProvisioningState         : Enabled
ServiceProviderProvisioningState : NotProvisioned
ServiceProviderNotes             :
ServiceProviderProperties        : {
                                     "ServiceProviderName": "Equinix",
                                     "PeeringLocation": "Silicon Valley",
                                     "BandwidthInMbps": 200
                                      }
ServiceKey                       : **************************************
Peerings                         : []

You can get detailed descriptions of all the parameters by running the following command:

get-help Get-AzureRmExpressRouteCircuit -detailed

5. Send the service key to your connectivity provider for provisioning

ServiceProviderProvisioningState provides information about the current state of provisioning on the service-provider side. Status provides the state on the Microsoft side. For more information about circuit provisioning states, see Workflows.

When you create a new ExpressRoute circuit, the circuit is in the following state:

ServiceProviderProvisioningState : NotProvisioned
CircuitProvisioningState         : Enabled

The circuit changes to the following state when the connectivity provider is in the process of enabling it for you:

ServiceProviderProvisioningState : Provisioning
Status                           : Enabled

For you to be able to use an ExpressRoute circuit, it must be in the following state:

ServiceProviderProvisioningState : Provisioned
CircuitProvisioningState         : Enabled

6. Periodically check the status and the state of the circuit key

Checking the status and the state of the circuit key lets you know when your provider has enabled your circuit. After the circuit has been configured, ServiceProviderProvisioningState appears as Provisioned, as shown in the following example:

Get-AzureRmExpressRouteCircuit -Name "ExpressRouteARMCircuit" -ResourceGroupName "ExpressRouteResourceGroup"

The response looks similar to the following example:

Name                             : ExpressRouteARMCircuit
ResourceGroupName                : ExpressRouteResourceGroup
Location                         : westus
Id                               : /subscriptions/***************************/resourceGroups/ExpressRouteResourceGroup/providers/Microsoft.Network/expressRouteCircuits/ExpressRouteARMCircuit
Etag                             : W/"################################"
ProvisioningState                : Succeeded
Sku                              : {
                                     "Name": "Standard_MeteredData",
                                     "Tier": "Standard",
                                     "Family": "MeteredData"
                                   }
CircuitProvisioningState         : Enabled
ServiceProviderProvisioningState : Provisioned
ServiceProviderNotes             :
ServiceProviderProperties        : {
                                     "ServiceProviderName": "Equinix",
                                     "PeeringLocation": "Silicon Valley",
                                     "BandwidthInMbps": 200
                                   }
ServiceKey                       : **************************************
Peerings                         : []

7. Create your routing configuration

For step-by-step instructions, see the ExpressRoute circuit routing configuration article to create and modify circuit peerings.

Important

These instructions only apply to circuits that are created with service providers that offer layer 2 connectivity services. If you're using a service provider that offers managed layer 3 services (typically an IP VPN, like MPLS), your connectivity provider configures and manages routing for you.

Next, link a virtual network to your ExpressRoute circuit. Use the Linking virtual networks to ExpressRoute circuits article when you work with the Resource Manager deployment model.

Getting the status of an ExpressRoute circuit

You can retrieve this information at any time by using the Get-AzureRmExpressRouteCircuit cmdlet. Making the call with no parameters lists all the circuits.

Get-AzureRmExpressRouteCircuit

The response is similar to the following example:

Name                             : ExpressRouteARMCircuit
ResourceGroupName                : ExpressRouteResourceGroup
Location                         : westus
Id                               : /subscriptions/***************************/resourceGroups/ExpressRouteResourceGroup/providers/Microsoft.Network/expressRouteCircuits/ExpressRouteARMCircuit
Etag                             : W/"################################"
ProvisioningState                : Succeeded
Sku                              : {
                                     "Name": "Standard_MeteredData",
                                     "Tier": "Standard",
                                     "Family": "MeteredData"
                                   }
CircuitProvisioningState         : Enabled
ServiceProviderProvisioningState : Provisioned
ServiceProviderNotes             :
ServiceProviderProperties        : {
                                        "ServiceProviderName": "Equinix",
                                        "PeeringLocation": "Silicon Valley",
                                        "BandwidthInMbps": 200
                                      }
ServiceKey                       : **************************************
Peerings                         : []

You can get information on a specific ExpressRoute circuit by passing the resource group name and circuit name as a parameter to the call:

Get-AzureRmExpressRouteCircuit -Name "ExpressRouteARMCircuit" -ResourceGroupName "ExpressRouteResourceGroup"

The response looks similar to the following example:

Name                             : ExpressRouteARMCircuit
ResourceGroupName                : ExpressRouteResourceGroup
Location                         : westus
Id                               : /subscriptions/***************************/resourceGroups/ExpressRouteResourceGroup/providers/Microsoft.Network/expressRouteCircuits/ExpressRouteARMCircuit
Etag                             : W/"################################"
ProvisioningState                : Succeeded
Sku                              : {
                                     "Name": "Standard_MeteredData",
                                        "Tier": "Standard",
                                        "Family": "MeteredData"
                                      }
CircuitProvisioningState         : Enabled
ServiceProviderProvisioningState : Provisioned
ServiceProviderNotes             :
ServiceProviderProperties        : {
                                     "ServiceProviderName": "Equinix",
                                     "PeeringLocation": "Silicon Valley",
                                     "BandwidthInMbps": 200
                                      }
ServiceKey                       : **************************************
Peerings                         : []

You can get detailed descriptions of all the parameters by running the following command:

get-help get-azurededicatedcircuit -detailed

Modifying an ExpressRoute circuit

You can modify certain properties of an ExpressRoute circuit without impacting connectivity.

You can do the following tasks with no downtime:

  • Enable or disable an ExpressRoute premium add-on for your ExpressRoute circuit.
  • Increase the bandwidth of your ExpressRoute circuit provided there is capacity available on the port. Downgrading the bandwidth of a circuit is not supported.
  • Change the metering plan from Metered Data to Unlimited Data. Changing the metering plan from Unlimited Data to Metered Data is not supported.
  • You can enable and disable Allow Classic Operations.

For more information on limits and limitations, see the ExpressRoute FAQ.

To enable the ExpressRoute premium add-on

You can enable the ExpressRoute premium add-on for your existing circuit by using the following PowerShell snippet:

$ckt = Get-AzureRmExpressRouteCircuit -Name "ExpressRouteARMCircuit" -ResourceGroupName "ExpressRouteResourceGroup"

$ckt.Sku.Tier = "Premium"
$ckt.sku.Name = "Premium_MeteredData"

Set-AzureRmExpressRouteCircuit -ExpressRouteCircuit $ckt

The circuit now has the ExpressRoute premium add-on features enabled. We begin billing you for the premium add-on capability as soon as the command has successfully run.

To disable the ExpressRoute premium add-on

Important

If you're using resources that are greater than what is permitted for the standard circuit, this operation can fail.

Note the following information:

  • Before you downgrade from premium to standard, you must ensure that the number of virtual networks that are linked to the circuit is less than 10. If you don't, your update request fails, and we bill you at premium rates.
  • You must unlink all virtual networks in other geopolitical regions. If you don't do this, your update request fails, and we bill you at premium rates.
  • Your route table must be less than 4,000 routes for private peering. If your route table size is greater than 4,000 routes, the BGP session drops and won't be reenabled until the number of advertised prefixes goes below 4,000.

You can disable the ExpressRoute premium add-on for the existing circuit by using the following PowerShell cmdlet:

$ckt = Get-AzureRmExpressRouteCircuit -Name "ExpressRouteARMCircuit" -ResourceGroupName "ExpressRouteResourceGroup"

$ckt.Sku.Tier = "Standard"
$ckt.sku.Name = "Standard_MeteredData"

Set-AzureRmExpressRouteCircuit -ExpressRouteCircuit $ckt

To update the ExpressRoute circuit bandwidth

For supported bandwidth options for your provider, check the ExpressRoute FAQ. You can pick any size greater than the size of your existing circuit.

Important

You may have to recreate the ExpressRoute circuit if there is inadequate capacity on the existing port. You cannot upgrade the circuit if there is no additional capacity available at that location.

You cannot reduce the bandwidth of an ExpressRoute circuit without disruption. Downgrading bandwidth requires you to deprovision the ExpressRoute circuit and then reprovision a new ExpressRoute circuit.

After you decide what size you need, use the following command to resize your circuit:

$ckt = Get-AzureRmExpressRouteCircuit -Name "ExpressRouteARMCircuit" -ResourceGroupName "ExpressRouteResourceGroup"

$ckt.ServiceProviderProperties.BandwidthInMbps = 1000

Set-AzureRmExpressRouteCircuit -ExpressRouteCircuit $ckt

Your circuit will be sized up on the Microsoft side. Then you must contact your connectivity provider to update configurations on their side to match this change. After you make this notification, we will begin billing you for the updated bandwidth option.

To move the SKU from metered to unlimited

You can change the SKU of an ExpressRoute circuit by using the following PowerShell snippet:

$ckt = Get-AzureRmExpressRouteCircuit -Name "ExpressRouteARMCircuit" -ResourceGroupName "ExpressRouteResourceGroup"

$ckt.Sku.Family = "UnlimitedData"
$ckt.sku.Name = "Premium_UnlimitedData"

Set-AzureRmExpressRouteCircuit -ExpressRouteCircuit $ckt

To control access to the classic and Resource Manager environments

Review the instructions in Move ExpressRoute circuits from the classic to the Resource Manager deployment model.

Deprovisioning and deleting an ExpressRoute circuit

Note the following information:

  • You must unlink all virtual networks from the ExpressRoute circuit. If this operation fails, check to see if any virtual networks are linked to the circuit.
  • If the ExpressRoute circuit service provider provisioning state is Provisioning or Provisioned you must work with your service provider to deprovision the circuit on their side. We continue to reserve resources and bill you until the service provider completes deprovisioning the circuit and notifies us.
  • If the service provider has deprovisioned the circuit (the service provider provisioning state is set to Not provisioned), you can delete the circuit. This stops billing for the circuit.

You can delete your ExpressRoute circuit by running the following command:

Remove-AzureRmExpressRouteCircuit -ResourceGroupName "ExpressRouteResourceGroup" -Name "ExpressRouteARMCircuit"

Next steps

After you create your circuit, make sure that you do the following next steps: