Connect to Microsoft
End users can create connections to AWS Direct Connect using either a Dot1q port or a QinQ port.
The following video shows how to connect to Azure Express Route using Equinix Fabric APIs.
Click here to download the postman scripts shown in this demo.
Layer 2 Connection to Azure ExpressRoute
Step 1: Retrieve Microsoft Service Key
Obtain a location-specific service key via the Azure portal.
Refer to https://docs.microsoft.com/en-us/azure/expressroute/expressroute-howto-circuit-portal-resource-manager for instructions on how to create a connection.
Step 2: Create Connection
2a) Authenticate
import StepAuthenticate, { toc as StepAuthenticateTOC } from '@site/fabric/_step-authenticate.mdx'
2b) Get the Port
Retrieve your allocated Equinix Fabric port information.
Refer to GET Port under the API Reference section for instructions on how to retrieve port details. You may skip this step if you already know your port information.
2c) Get Metros
Find all metros where Equinix Fabric is available to check if a connection can be established between the port selected earlier and your desired destination metro.
Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your connection.
Refer to GET Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know this information.
2d) Get Service Profile
Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.
Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in Equinix Fabric. You may skip this step if you already know the service profile details.
2e) Get ValidateAuthorizationKey
Verify whether your Azure service key can be used to create a connection to the seller profile selected in the previous step.
Refer to GET validateAuthorizationKey under the API Reference section for instructions on how to validate your authorization key. You may skip this step if you are certain that your key is authorized for creating connections with the selected service profile.
2f) Post Connections
| POST /ecx/v3/l2/connections | |
|---|---|
| Method | POST |
| URL or Endpoint | /ecx/v3/l2/connections |
| Headers | Authorization, Content-Type |
| Query Parameters | Not applicable |
| Body Parameters | primaryName, primaryPortUUID, primaryVlanSTag, profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerMetroCode, secondaryName, secondaryPortUUID, secondaryVlanSTag, secondaryVlanCTag, namedTag, primaryZSideVlanCTag, secondaryZSideVlanCTag, |
The POST connections API creates a layer 2 connection between your port and the destination service profile. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.
If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens section under the Getting Access Token.
The following screenshots show a sample curl request to create a layer 2 Azure connection using a Dot1q and QinQ port and a sample JSON response for this API.
Should you want to estimate the price of this connection, use the API GET Prices.
Azure Express Route connection using a Dot1q port
curl -X
POST "https://api.equinix.com/ecx/v3/l2/connections"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
"primaryName": "JohnDoe_Dot1q_Private",
"profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
"speed": 50,
"speedUnit": "MB",
"purchaseOrderNumber": "",
"primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
"primaryVlanSTag": "458",
"secondaryName": "TestS110",
"secondaryVlanSTag": "442",
"secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
"namedTag": "Private",
"sellerMetroCode": "SV",
"authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
"notifications": [
"JohnDoe@example.com"
]
}'
C Tag is not applicable for "Private", "Public" and "Microsoft" peering.
curl -X
POST "https://api.equinix.com/ecx/v3/l2/connections"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
"primaryName": "JohnDoe_Dot1q_Manual",
"profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
"speed": 50,
"speedUnit": "MB",
"purchaseOrderNumber": "",
"primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
"primaryVlanSTag": "458",
"secondaryName": "TestS110",
"secondaryVlanSTag": "442",
"secondaryZSideVlanCTag": "542",
"primaryZSideVlanCTag":"558",
"secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
"namedTag": "Manual",
"sellerMetroCode": "SV",
"authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
"notifications": [
"JohnDoe@example.com"
]
}'
Azure Express Route connection using a QinQ port
curl -X
POST "https://api.equinix.com/ecx/v3/l2/connections"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
"purchaseOrderNumber": "1234567890",
"primaryName": "JohnDoe_Azure_QinQ",
"secondaryName": "JohnDoe2_Azure_QinQ",
"primaryPortUUID": "7f891d3b-973d-73d0-bae0-30ac1885197a",
"secondaryPortUUID": "7f891d3b-973d-73d0-bae0-30ac1885197a",
"primaryVlanSTag": 640,
"secondaryVlanSTag": 650,
"profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
"authorizationKey": "e03da869-8243-4dac-ae49-a95c80f5425d",
"sellerMetroCode": "DC",
"speed": 50,
"speedUnit": "MB",
"notifications": [
"JohnDoe@example.com"
],
}'
The description of the body parameters is as follows:
| Body Parameter Name | Mandatory | Type | Example | Applicable Values | Description |
|---|---|---|---|---|---|
| primaryName | Yes | string | JohnDoe_Dot1q_Manual | User-defined name of the primary connection. Supply an alpha-numeric string, which can include hyphens and underscores ('-' & '_') as special characters (no other special characters are allowed). Max Length: 24 characters | |
| primaryPortUUID | Yes | string | 7f891d3b-973d-73d0-bae0-30ac1885197a | Unique Equinix-assigned ID of the buyer's primary port from where the connection originates. | |
| primaryVlanSTag | Yes | integer | 640 | S-Tag/Outer-Tag of the primary connection. Range: 2 - 4094 | |
| profileUUID | Yes | string | 84c6616c-573a-447d-a478-9fab8fff284d | Unique Equinix-assigned ID of the provider's service profile. | |
| authorizationKey | Yes | string | e03da869-8243-4dac-ae49-a95c80f5425d | Authorization Key provided by Azure. For example, the Service Key from Azure Express Route. | |
| speed | No | integer | 50 | Speed/bandwidth to be allocated to the connection. | |
| speedUnit | No | string | MB | Unit of the speed/bandwidth to be allocated to the connection. Values: Either MB or GB. | |
| notifications | Yes | array | JohnDoe@example.com | A list of email addresses that are notified when there are any updates on this connection. Example: ["user@example.com", "user2@example.com"] | |
| purchaseOrderNumber | Yes | string | This optional field links the purchase order to the connection on Equinix. This link is reflected on the invoice. | ||
| sellerMetroCode | Yes | string | DC | The metro code that denotes the connection’s destination (Z side). If sellerMetroCode is empty, the value defaults to the metro code of the port. | |
| secondaryName | Yes | string | JohnDoe2_Azure_QinQ | Name of the secondary connection. Supply an alpha-numeric string, which can include hyphens and underscores ('-' & '_') as special characters (no other special characters are allowed). Max Length: 24 characters | |
| secondaryPortUUID | Yes | string | 7f891d3b-973d-73d0-bae0-30ac1885197a | Unique ID of the buyer's secondary port from which the secondary connection would originate. | |
| secondaryZSideVlanSTag | Yes | integer | 442 | S-Tag/Outer-Tag of the secondary connection. Range: 2 - 4094 | |
| secondaryZSideVlanCTag | Yes | integer | 542 | C-Tag/Inner-Tag of the secondary connection. Range: 2 - 4094 | |
| namedTag | Yes | string | Private | "Private" "Public" "Microsoft" "Manual" | The type of peering to set up with Azure Express Route. |
| primaryZSideVlanCTag | Yes | integer | 558 | C-Tag/Inner-Tag of the primary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag = "Manual"). Range: 2 - 4094 | |
| secondaryZSideVlanCTag | Yes | integer | 542 | C-Tag/Inner-Tag of the secondary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag = "Manual"). Range: 2 - 4094 |
Equinix Fabric participants with Dot1q ports can create up to three connections to Azure using the same Azure service key. However, all 3 connections must have different namedTags such as "private", "public", "Microsoft" or "Manual" peering. Note that "Microsoft" peering requires special permission from Microsoft. Equinix Fabric participants with QinQ ports only need to create one primary and one redundant connection. When creating a connection to Azure, the payload expectations with regard to c-tags and s-tags vary based on the type of port (Dot1q or QinQ) from which you are creating a connection to Azure. The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to Azure Express Route (Z - side QinQ).
| Port Type (A-side) | Maximum Number Of Connections | Peering Type (indicated by namedTag field) | S-tag required | C-tag required | Port Type (Z-side) |
|---|---|---|---|---|---|
| Dot1q port | 3 pairs (3 primary and 3 redundant) | Public | Yes | No. Note: Only a Z side C-tag is required and it is provided under VLANID while setting up peering in Azure portal. | QinQ port |
| Private | Yes | No. Note: Only a Z side C-tag is required and it is provided under VLANID while setting up peering in Azure portal. | |||
| Microsoft | Yes | No. Note: Only a Z side C-tag is required and it is provided under VLANID while setting up peering in Azure portal. | |||
| Manual | Yes | Yes. Note: Only a Z side C-tag is required, and it is provided in the Equinix Fabric portal or in the API request payload. | |||
| QinQ port | 1 pair (1 primary and 1 redundant) | Public | Yes | No | |
| Private | Yes | No | |||
| Microsoft | Yes | No | |||
| Manual | Yes | No |
If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Fabric Portal access.
{
"message": "Connection Saved Successfully",
"primaryConnectionId": "9994b8d-dcdb-45bc-b760-55368e16f3c4",
"secondaryConnectionId": "888d4c1-5444-4511-b2e4-51f06f062974"
}
The description of the response payload is as follows:
| Field Name | Type | Example | Description |
|---|---|---|---|
| message | string | Connection Saved Successfully | Indicates the status of the API call. |
| primaryConnectionId | string | 9994b8d-dcdb-45bc-b760-55368e16f3c4 | Indicates the primary connection ID of the connection that was just created. |
| secondaryConnectionId | string | 888d4c1-5444-4511-b2e4-51f06f062974 | Indicates the secondary connection ID of the connection that was just created. |
Once the POST Connections API is successfully called, you may check the status of the connection using the API GET Connections{uuid}.
Should you want to upgrade the speed/bandwidth of this connection, you can use the API PATCH Connections{uuid}.
When a connection is created, the connection transitions through various states within the Equinix and Azure infrastructure. These states can be monitored using the response attributes of the API GET Connections{uuid}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status in Azure.
| Equinix States under /ecx/v3/l2/connections/{connId} | Azure States | |||
| "status" attribute values | "providerStatus" attribute values | Azure's Provider Status | Azure's Peerings Status | Description |
| PROVISIONING | NOT_AVAILABLE | Not provisioned | Not provisioned | Connection request has not been yet sent to Microsoft Azure. |
| PENDING_BGP_PEERING | PENDING_BGP | Provisioned | Not provisioned | The connection has been approved and awaits for the customer to configure Microsoft peering on the Azure portal. Note that the status will be “PENDING_BGP_PEERING” until peering is completed in the Azure portal and the status will only change to "PROVISIONED" once Equinix Fabric syncs with Microsoft. If you want to synchronize the BGP peering instantly, you may use the Equinix Fabric Portal. |
| PROVISIONING | PROVISIONED | Provisioned | Provisioned | Provisioning completed at Microsoft's end and the connection is provisioning at Equinix's end. |
| PROVISIONED | PROVISIONED | Provisioned | Provisioned | The connection is provisioned. |
Refer https://docs.microsoft.com/en-us/azure/expressroute/expressroute-howto-circuit-portal-resource-manager for the different Azure Express Route states.
When an end user deletes a connection using the API DELETE Connections{uuid} the connection transitions through the following states within the Equinix infrastructure.
| Equinix States under /ecx/v3/l2/connections/{connId} | ||
| "status" attribute values | "providerStatus" attribute values | Description |
| DEPROVISIONING | PROVISIONED | Connection disbandment in progress. |
| DEPROVISIONED | DEPROVISIONED | Connection deleted. |
Step 3: Setup Microsoft Peering
Configure BGP peering on the Azure portal and call the below API to synchronize the peering changes with Equinix. Once it is completed, the connection status retrieved via the GET Connections{uuid} should change from “Pending-BGP-Peering” to “Provisioned”. Alternatively, you can also synchronize the peering using the Equinix portal.
Refer to https://docs.microsoft.com/en-us/azure/expressroute/expressroute-howto-routing-portal-resource-manager for instructions on how to configure peering for an Express Route connection.