Quickstart: Create and modify an ExpressRoute circuit using Azure CLI
This quickstart describes how to create an Azure ExpressRoute circuit by using the Command Line Interface (CLI). This article also shows you how to check the status, update, or delete and deprovision a circuit.
Prerequisites
- Review the prerequisites and workflows before you begin configuration.
- An Azure account with an active subscription. Create an account for free.
- Install the latest version of the CLI commands (2.0 or later). For information about installing the CLI commands, see Install the Azure CLI and Get Started with Azure CLI.
Azure Cloud Shell
Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.
To start Azure Cloud Shell:
| Option | Example/Link |
|---|---|
| Select Try It in the upper-right corner of a code or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell. |  |
| Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. |  |
| Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. |  |
To use Azure Cloud Shell:
Start Cloud Shell.
Select the Copy button on a code block (or command block) to copy the code or command.
Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.
Select Enter to run the code or command.
Create and provision an ExpressRoute circuit
Sign in to your Azure account and select your subscription
To begin your configuration, sign in to your Azure account. If you use the Cloud Shell Try It, you're signed in automatically. Use the following examples to help you connect:
az login
Check the subscriptions for the account.
az account list
Select the subscription for which you want to create an ExpressRoute circuit.
az account set --subscription "<subscription ID>"
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 CLI command az network express-route list-service-providers returns this information, which you use in later steps:
az network express-route list-service-providers
The response is similar to the following example:
[
{
"bandwidthsOffered": [
{
"offerName": "50Mbps",
"valueInMbps": 50
},
{
"offerName": "100Mbps",
"valueInMbps": 100
},
{
"offerName": "200Mbps",
"valueInMbps": 200
},
{
"offerName": "500Mbps",
"valueInMbps": 500
},
{
"offerName": "1Gbps",
"valueInMbps": 1000
},
{
"offerName": "2Gbps",
"valueInMbps": 2000
},
{
"offerName": "5Gbps",
"valueInMbps": 5000
},
{
"offerName": "10Gbps",
"valueInMbps": 10000
}
],
"id": "/subscriptions//resourceGroups//providers/Microsoft.Network/expressRouteServiceProviders/",
"location": null,
"name": "AARNet",
"peeringLocations": [
"Melbourne",
"Sydney"
],
"provisioningState": "Succeeded",
"resourceGroup": "",
"tags": null,
"type": "Microsoft.Network/expressRouteServiceProviders"
},
Check the response to see if your connectivity provider is listed. Make a note of the following information, which you need when you create a circuit:
- Name
- PeeringLocations
- BandwidthsOffered
You're now ready to create an ExpressRoute circuit.
Create an ExpressRoute circuit
Important
Your ExpressRoute circuit is billed from the moment a service key is issued. Perform this operation when the connectivity provider is ready to provision the circuit.
If you don't already have a resource group, you must create one before you create your ExpressRoute circuit. You can create a resource group by running the following command:
az group create -n ExpressRouteResourceGroup -l "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, replace that information when you make your request.
Make sure that you specify the correct SKU tier and SKU family:
- SKU tier determines whether an ExpressRoute circuit is Local, Standard, or Premium. You can specify Local, *Standard, or Premium.
- 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. A Local circuit is UnlimitedData only.
Your ExpressRoute circuit is billed from the moment a service key is issued. The following example is a request for a new service key:
az network express-route create --bandwidth 200 -n MyCircuit --peering-location "Silicon Valley" -g ExpressRouteResourceGroup --provider "Equinix" -l "West US" --sku-family MeteredData --sku-tier Standard
The response contains the service key.
List all ExpressRoute circuits
To get a list of all the ExpressRoute circuits that you created, run the az network express-route list command. You can retrieve this information at any time by using this command. To list all circuits, make the call with no parameters.
az network express-route list
Your service key is listed in the ServiceKey field of the response.
"allowClassicOperations": false,
"authorizations": [],
"circuitProvisioningState": "Enabled",
"etag": "W/\"1262c492-ffef-4a63-95a8-a6002736b8c4\"",
"gatewayManagerEtag": null,
"id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ExpressRouteResourceGroup/providers/Microsoft.Network/expressRouteCircuits/MyCircuit",
"location": "westus",
"name": "MyCircuit",
"peerings": [],
"provisioningState": "Succeeded",
"resourceGroup": "ExpressRouteResourceGroup",
"serviceKey": "1d05cf70-1db5-419f-ad86-1ca62c3c125b",
"serviceProviderNotes": null,
"serviceProviderProperties": {
"bandwidthInMbps": 200,
"peeringLocation": "Silicon Valley",
"serviceProviderName": "Equinix"
},
"serviceProviderProvisioningState": "NotProvisioned",
"sku": {
"family": "UnlimitedData",
"name": "Standard_MeteredData",
"tier": "Standard"
},
"tags": null,
"type": "Microsoft.Network/expressRouteCircuits]
You can get detailed descriptions of all the parameters by running the command using the '-h' parameter.
az network express-route list -h
Send the service key to your connectivity provider for provisioning
'ServiceProviderProvisioningState' provides information about the current state of provisioning on the service-provider side. The status provides the state on the Microsoft side. For more information, see the Workflows article.
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 currently enabling it for you:
"serviceProviderProvisioningState": "Provisioning"
"circuitProvisioningState": "Enabled"
To use the ExpressRoute circuit, it must be in the following state:
"serviceProviderProvisioningState": "Provisioned"
"circuitProvisioningState": "Enabled
Periodically check the status and the state of the circuit key
Checking the status and the state of the service key lets you know when your provider has provisioned your circuit. After the circuit has been configured, ServiceProviderProvisioningState appears as Provisioned, as shown in the following example:
az network express-route show --resource-group ExpressRouteResourceGroup --name MyCircuit
The response is similar to the following example:
"allowClassicOperations": false,
"authorizations": [],
"circuitProvisioningState": "Enabled",
"etag": "W/\"1262c492-ffef-4a63-95a8-a6002736b8c4\"",
"gatewayManagerEtag": null,
"id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ExpressRouteResourceGroup/providers/Microsoft.Network/expressRouteCircuits/MyCircuit",
"location": "westus",
"name": "MyCircuit",
"peerings": [],
"provisioningState": "Succeeded",
"resourceGroup": "ExpressRouteResourceGroup",
"serviceKey": "1d05cf70-1db5-419f-ad86-1ca62c3c125b",
"serviceProviderNotes": null,
"serviceProviderProperties": {
"bandwidthInMbps": 200,
"peeringLocation": "Silicon Valley",
"serviceProviderName": "Equinix"
},
"serviceProviderProvisioningState": "NotProvisioned",
"sku": {
"family": "UnlimitedData",
"name": "Standard_MeteredData",
"tier": "Standard"
},
"tags": null,
"type": "Microsoft.Network/expressRouteCircuits]
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.
Link a virtual network to an ExpressRoute circuit
Next, link a virtual network to your ExpressRoute circuit. Use the Linking virtual networks to ExpressRoute circuits article.
Modifying an ExpressRoute circuit
You can modify certain properties of an ExpressRoute circuit without impacting connectivity. You can make the following changes with no downtime:
- You can enable or disable an ExpressRoute premium add-on for your ExpressRoute circuit.
- You can increase the bandwidth of your ExpressRoute circuit provided there's capacity available on the port. However, downgrading the bandwidth of a circuit isn't supported.
- You can change the metering plan from Metered Data to Unlimited Data. However, changing the metering plan from Unlimited Data to Metered Data isn't 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 command:
az network express-route update -n MyCircuit -g ExpressRouteResourceGroup --sku-tier Premium
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
This operation can fail if you're using resources that are greater than what is permitted for the standard circuit.
Before disabling the ExpressRoute premium add-on, understand the following criteria:
- 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.
- All virtual networks in other geopolitical regions must be first unlinked. If you don't remove the link, your update request fails and we continue to 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. The BGP session doesn't reestablish until the number of advertised prefixes is under 4,000.
You can disable the ExpressRoute premium add-on for the existing circuit by using the following example:
az network express-route update -n MyCircuit -g ExpressRouteResourceGroup --sku-tier Standard
To update the ExpressRoute circuit bandwidth
For the supported bandwidth options for your provider, check the ExpressRoute FAQ. You can pick any size greater than the size of your existing circuit.
Important
If there is inadequate capacity on the existing port, you may have to recreate the ExpressRoute circuit. 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 the size you need, use the following command to resize your circuit:
az network express-route update -n MyCircuit -g ExpressRouteResourceGroup --bandwidth 1000
Your circuit is upgraded on the Microsoft side. Next, you must contact your connectivity provider to update configurations on their side to match this change. After you make this notification, we 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 example:
az network express-route update -n MyCircuit -g ExpressRouteResourceGroup --sku-family UnlimitedData
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 an ExpressRoute circuit
To deprovision and delete an ExpressRoute circuit, make sure you understand the following criteria:
- All virtual networks must be unlinked 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 meaning the service provider provisioning state gets set to Not provisioned, you can delete the circuit. The billing for the circuit stop.
Clean up resources
You can delete your ExpressRoute circuit by running the following command:
az network express-route delete -n MyCircuit -g ExpressRouteResourceGroup
Next steps
After you create your circuit and provision it with your provider, continue to the next step to configure the peering: