Launch Equinix-Configured Device
A customer will have less control of an Equinix-Configured device compared to a Self-Configured device. The Equinix-Configured option can be thought of as a PaaS deployment, whereas the Self-Configured option is IaaS. Here are the steps to create an Equinix-Configured device:
1) Find out the following information:
- the device type you want (deviceTypeCode)
- the number of cores you need (core)
- the software type you want (packageCode and version)
- the location where you want your virtual device (metroCode)
2) You must have your Equinix account number ready. Your account must be in the Active or Pending status.
3) Figure out the licensing option (licenseMode) you want. If you opt for a subscription license, Equinix will manage and charge monthly. We offer subscription licenses for Cisco devices. If you want to bring your own license, upload the license file/token from your vendor.
Note: Sub-customers cannot choose the subscription licensing option. Even resellers creating devices for sub-customers can only choose the BYOL licensing option. See Step 3 to learn how to bring your own license.
4) Include the Id of an existing or a new ACL template in your payload. To create an ACL template, call the Create ACL Template method. Once you have the unique Id of the ACL template, pass the template Id when creating a new device.
Note: By creating a virtual device, you accept the Order Terms. Call Get Order Terms to review the details. If you are creating an Equinix-Configured device, you can read your vendor's terms by calling Get Vendor Terms.
If you have all the necessary information, skip ahead to Step 4 and create a virtual device. Otherwise, follow the steps:
To save a device draft, you must provide the deviceTypeCode, accountNumber/accountReferenceId, and metroCode.
See the Network Edge deployment guide to understand the pre-requisites to bring your own license option (BYOL). You will also find details about additional services like BGP peering and VPN configuration.
Step 1: Authenticate
Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.
See Generating Client id and Client Secret under the Getting Access Token section for instructions to create a client ID and client secret. See Requesting Access and Refresh tokens for instructions to call the Oauth API to validate and authenticate your credentials.
If you are unaware of your user credentials, contact your local Equinix Service Desk.
Step 2: Get Device Types and Account
2a) Get device types
Call Get Device Types API to find out which virtual device (e.g., router or firewall) you want to launch on the NE platform (deviceTypeCode). You will learn about the metro regions where virtual devices are available (metroCode), the vendors of devices, the available number of cores (core) and software packages (packageCode and version), and all possible licensing and throughput options.
2b) Get account
Call Get Accounts {metro} API to check your account number (or acountReferenceId) and status in the metro where you want a virtual device. For billing reasons, you must have an account in the metro where you want a virtual device, either in the Active or Pending state. To learn how to create an account, refer to Billing Account Management.
If you are a reseller trying to create a device for your customer, you must ensure that the customer's and your (reseller's) accounts are both in the Active or Pending status. Your account will get billed, however, you must send the customer's account number to the POST API to create a device for your customer.
Step 3: Licensing Options
If you want to bring your own license (BYOL), you must upload a license file or a license code/token/ID, depending on what your vendor offers.
For Cisco devices, you must provide a license token at the time you create a device if you wish to BYOL.
Some vendors provide a license file that you can upload to create a device if you wish to BYOL.
There are three APIs to address each of the licensing scenarios in case you want to bring your own license (BYOL). Refer to the Network Edge Deployment Guide for licensing options of the available virtual devices.
3a) Posting a license when creating a device (BYOL)
If you have a license file, use the Post License File API to upload the file. You will get a file ID that you can use to create a virtual device.
For a Cisco device, enter a license token in the create device payload to bring your own license (BYOL).
3b) Posting a license after creating a device (BYOL)
If your license is not registered (REGISTRATION_FAILED) although your device is provisioned, use the Post License {uuid} API to re-post a license file. You must upload two files in case you have a redundant device.
3c) Update a license code/token/ID
If you have a Cisco device, you can use the Update License API to update a license token/code/ID in case the license fails to register (REGISTRATION_FAILED). You may use the same or two different tokens in case you have a redundant device.
Step 4: Create Virtual Device
| POST /ne/v1/devices | |
|---|---|
| Method | POST |
| URL or End Point | /ne/v1/devices |
| Headers | Authorization token, Content-Type |
| Query Parameters | draft, draftUuid |
| Body Parameters | additionalBandwidth, deviceTypeCode, diverseFromDeviceUuid, hostNamePrefix, licenseFileId, licenseMode, licenseToken, agreeOrderTerms, metroCode, notifications[...], packageCode, version, termLength, throughput, throughputUnit, virtualDeviceName, orderingContact, aclDetails[{uuid, interfaceType}], accountNumber, accountReferenceId, purchaseOrderNumber, interfaceCount, deviceManagementType, core, channelPartner, secondary {accountNumber, accountReferenceId, additionalBandwidth, licenseFileId, licenseToken, metroCode, notifications[...], aclDetails[{uuid, interfaceType}], sshUsers[{sshUserUuid, action, sshUsername, sshPassword}], virtualDeviceName, hostNamePrefix"} |
If you wish to create a redundant device that has two devices, primary and secondary, please do the following:
1) Set parameters of the optional secondary object
2) Keep in mind, both the devices use the same license type, either SUB (subscription) or BYOL (bring your own license). In case you want to BYOL, you may or may not need two different license files or tokens, depending on your choice of vendor.
a) For a Cisco redundant device, you may use the same license token for the primary and secondary devices.
3) If you are a reseller trying to create a redundant device for your customer, please make sure both the primary and secondary metros are in the same country. Also, the primary and secondary account numbers must be the same. The reseller's account will get billed, however, this API accepts the customer's account number to create devices for the customer. The above restrictions are necessary as each customer is associated with a reseller's billing account.
To obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.
A sample curl request to create a virtual device.
curl -X
POST "https://api.equinix.com/ne/v1/devices?draft=false"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '{
"throughput":500,
"throughputUnit":"Mbps",
"metroCode":"DC",
"deviceTypeCode":"CSR1000V",
"termLength":"12",
"agreeOrderTerms": true,
"licenseMode":"Sub",
"packageCode":"SEC",
"version": "16.09.03",
"virtualDeviceName":"Test-device-006-SROY",
"notifications":["mest@equinix.com","test@equinix.com"],
"hostNamePrefix":"SROY123",
"sshUsers":[{"action":"CREATE","sshUsername":"tatiyana1","sshPassword":"Tatiyana"},{"action":"REUSE","sshUserUuid":"72902689-dff7-437d-8832-4bc8f3495252"}],
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"purchaseOrderNumber":"234567",
"accountNumber":"2252619",
"additionalBandwidth":"100",
"deviceManagementType": "EQUINIX-CONFIGURED",
"core": 4,
"interfaceCount": 24,
"channelPartner": "SDCI"
}'
A sample curl request to create a redundant device.
curl -X
POST "https://api.equinix.com/ne/v1/devices?draft=false"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '{
"throughput":500,
"throughputUnit":"Mbps",
"metroCode":"DC",
"agreeOrderTerms": true,
"deviceTypeCode":"CSR1000V",
"termLength":"12",
"licenseMode":"Sub",
"packageCode":"SEC",
"version": "16.09.03",
"virtualDeviceName":"Test-device-006-SROY",
"notifications":["mest@equinix.com","test@equinix.com"],
"hostNamePrefix":"SROY123",
"sshUsers":[{"action":"CREATE","sshUsername":"tatiyana1","sshPassword":"Tatiyana"},{"action":"REUSE","sshUserUuid":"72902689-dff7-437d-8832-4bc8f3495252"}],
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"purchaseOrderNumber":"234567",
"accountNumber":"2252619",
"deviceManagementType": "EQUINIX-CONFIGURED",
"core": 4,
"interfaceCount": 24,
"channelPartner": "SDCI",
"secondary":
{"metroCode":"DC",
"notifications":["test@gmail.com"],
"virtualDeviceName":"Test-device-006-SROY - secondary",
"hostNamePrefix":"SROY-SEC",
"additionalBandwidth":"200",
"sshUsers":[{"action":"CREATE","sshUsername":"mekana12","sshPassword":"testPassword"},{"action":"REUSE","sshUserUuid":"72902689-dff7-437d-8832-4bc8f3495252"},
{"action":"REUSE","sshUserUuid":"a394dee9-d71d-4446-9210-c948cdd18a4b"}],
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"accountNumber":"2252619"},
"additionalBandwidth":"100"
}'
Query parameters:
| Query Parameter Name | Mandatory | Type | Example | Possible Values | Description |
|---|---|---|---|---|---|
| draft | No | boolean | False | True, False | Default=false. To save a draft, set draft=true. You must provide deviceTypeCode, accountNumber/accountReferenceId, and metroCode to save a draft. SshUsers and licenseFileId information will not be saved for drafts. Also, this API will not do access-control validation when you save a draft. |
| draftUuid | No | string | ec68e425-f973-452e-a866-76be5844d0ba | To create a device from a draft that you saved earlier, provide the unique Id of the draft (draftUuid). |
Body parameters:
| Body Parameter Name | Mandatory | Type | Example | Possible Values | Description |
|---|---|---|---|---|---|
| deviceTypeCode | Yes | string | CSR1000V | Virtual device type (device type code). | |
| diverseFromDeviceUuid | No | string | 4cfb5675-5c3f-4275-adba-0c9e3c26c96b | Unique Id of an existing device. Use this field to let Equinix know if you want your new device to be in a different location from any existing virtual device. This field is only meaningful for single devices. | |
| accountNumber | No | string | 10478397 | Account number. Either an account number or an account referenceId is required to create a virtual device. Note to resellers creating a device for a customer: Your (reseller's) account will get billed, however, you must send the customer's account number to this API to create a device for your customer. | |
| accountReferenceId | No | string | 791281 | Account reference Id. This is a temporary ID that can be used to create a device when your account is still pending, not active. Either an account number or an account referenceId is required to create a virtual device. | |
| hostNamePrefix | Yes | string | mySR | Host name. This gets included as FQDN and ensures the device is reachable from the approved sources. Only a-z, A-Z, 0-9, and hyphen(-) are allowed. It should start with a letter and end with a letter or a digit. The length should be between 2-30 characters. Exceptions - Aruba 2-24; and FTDv 2-14. | |
| virtualDeviceName | Yes | string | CiscoSTROY | The virtual device name for identification. This should be a minimum of 3 and a maximum of 50 characters long. | |
| orderingContact | No | string | subuser01 | Username of a reseller's customer. This field is mandatory in case a reseller is ordering a device for one of its customers. This contact will receive order and cancellation notifications. | |
| licenseFileId | No | string | 6651aef5-e738-411f-8675-5f6b7b9cd429 | LicensefileId is mandatory for some vendors. If you select a subscription license model (SUB), then you do not need to provide a licenseFileId. | |
| licenseMode | Yes | string | BYOL | BYOL, SUB | License type. One of SUB (subscription) or BYOL (bring your own license). |
| licenseToken | No | string | V74191621 | License token is mandatory for vendors that provide/accept a license token. You do not need to provide a license token if you want a subscription model or if your vendor provides license files. For Cisco devices, you may use the same token for both the primary and secondary devices. | |
| agreeOrderTerms | Yes | boolean | true | To create a device, you must agree to the order terms. See Get Order Terms to review the details. If you are creating an Equinix-Configured device, read your vendor's terms by calling Get Vendor Terms. | |
| metroCode | Yes | string | SV | Metro code. You may choose two different metros if you are creating two devices for redundancy. However, both metros must be in the same country if you are a reseller trying to create a device for your customer. This restriction is necessary as a customer is associated with a reseller's billing account. | |
| notifications | Yes | array | test1@example.com | Email addresses for device life-cycle notifications. We need a minimum of 1 and no more than 5 email addresses. You may have a different notification list for your secondary device. | |
| packageCode | Yes | string | VM100 | Software package code. | |
| version | Yes | string | 16.09.03 | Version. | |
| sshUsers | No | array[object] | { "sshUserUuid": "", "action": "CREATE", "sshUsername": "cust00011_DCT", "sshPassword": "projPass!" } | SSH users. You may have two distinct sets of ssh users in case you have a redundant device. | |
| termLength | No | integer | 24 | 1, 12, 24, 36. | Billing term length in months. |
| throughput | No | integer | 500 | Throughput. Mandatory for most devices, e.g. CSR1000V. | |
| throughputUnit | No | string | Mbps | Throughput unit. Mandatory for most devices, e.g. CSR1000V. | |
| aclDetails | Yes | array | "aclDetails": [ { "uuid":"fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2", "interfaceType": "WAN" } ] | An array of ACLs. | |
| aclDetails.uuid | Yes | string | 39289456-a63e-47d4-927c-5161cfb77500 | The template Id of an ACL template created using Create ACL Template. | |
| aclDetails.interfaceType | Yes | string | WAN | Interface type, either WAN or MGMT. Only some device types support MGMT interface ACLs. | |
| purchaseOrderNumber | No | string | 3456789 | Purchase order number. Optional field that customers can use to tie a device with its purchase order number. | |
| additionalBandwidth | No | integer | 100 | Additional bandwidth. You may have a different additional bandwidth for your secondary device in case you have a redundant device. | |
| deviceManagementType | Yes | string | EQUINIX-CONFIGURED | Whether the device is managed by Equinix or self-configured. This use case addresses EQUINIX-CONFIGURED devices. | |
| core | Yes | integer | 4 | The number of cores. | |
| interfaceCount | No | integer | 24 | Interface count. To find out the allowed number of interfaces for your selected core, call Get Allowed Interfaces. | |
| secondary | No | object | secondary{} | Object containing the optional secondary device details. | |
| sshUserUuid | No | string | ef673cd4-9fc2-4ab4-810e-7274aaf7bc2d | Required for DELETE, REUSE operations. In case you want to REUSE an existing user, please provide the unique Id of the user. | |
| action | No | string | CREATE | CREATE, DELETE, REUSE | Action to be performed. |
| sshUsername | No | string | cust00011_DCT | SSH Username | |
| sshPassword | No | string | projPass! | SSH Password | |
| channelPartner | No | string | SDCI | The name of the channel partner. |
Note: "aclTemplateUuid" field is deprecated. Please use "aclDetails" instead.
Sample response for a single device.
202: Request accepted.
{
"uuid": "74d8c6b6-3153-4271-9f0e-45bdc7094dec"
}
Sample response for a virtual device with an additional secondary device for redundancy.
202: Request accepted.
{
"uuid": "74d8c6b6-3153-4271-9f0e-45bdc7094dec",
"secondaryUuid": "de5cf79b-3d16-4ccd-841b-3b68ecda2142"
}
Response payload:
| Field | Type | Example Values | Description |
|---|---|---|---|
| uuid | string | b43ba509-a7d9-4334-8dee-dc4f29bf2e77 | Unique identifier of the virtual device. |
| secondaryUuid | string | 92c2e49d-2c35-432d-a9af-016920bef70c | Unique identifier of the secondary virtual device. |
When a device is created, the device transitions through various states within the Equinix infrastructure. These states can be monitored using the "status" response attribute of the Get Virtual Device {uuid} API. Your device must be provisioned and your license must be registered before you can use this virtual device to connect to cloud service providers and take advantage of other services, like BGP peering and VPN termination.
| Virtual device "status" | Description |
|---|---|
| INITIALIZING | Equinix is in the process of reserving resources and creating the device. |
| PROVISIONING | The device is booting. |
| PENDING_ORDER | This status only applies to orders coming to NE from Siebel. Customers need to log in to the Network Edge portal and submit the pending order. |
| PENDING_SIGNATURE | The customer has not yet accepted Network Edge terms. |
| CANCEL_ORDER | The order from Siebel to NE is canceled. This status only applies to orders coming to Network Edge from Siebel. |
| WAITING_FOR_PRIMARY | The secondary device is ready, but the primary is not. This state may appear only if you have created a secondary device for redundancy. |
| WAITING_FOR_SECONDARY | The primary device is ready, but the secondary is not. This state may appear only if you have created a secondary device for redundancy. |
| FAILED | The device creation failed. |
| PROVISIONED | The device is ready. |
When end-users delete a device using the Delete Virtual Devices API, the device transitions through the following states within the Equinix infrastructure.
| Virtual device "status" under /ne/v1/devices/{uuid} | Description |
|---|---|
| DEPROVISIONING | Equinix accepted your request to delete a virtual device. |
| DEPROVISIONED | The device is de-provisioned/deleted. |
Sample Payloads (Equinix-Configured Devices)
Download Postman Scripts for exact payloads to create devices.
| Parameter Name | CSR1000V subscription | CSR1000V BYOL |
|---|---|---|
| deviceTypeCode | CSR1000V | CSR1000V |
| hostNamePrefix | myHost123 | myHost123 |
| agreeOrderTerms | true | true |
| licenseMode | Sub | BYOL |
| licenseToken | ZTRjZTdlYmYtZjQ3 | |
| licenseFileId | ||
| notifications | test@equinix.com | test@equinix.com |
| metroCode | DC | DC |
| aclDetails.uuid | nf92ee6f-286f-496e-b4a1-7b4d1802109m | nf92ee6f-286f-496e-b4a1-7b4d1802109m |
| aclDetails.interfaceType | WAN | WAN |
| packageCode | SEC | SEC |
| version | 16.12.03 | 16.12.03 |
| throughput | 500 | 500 |
| throughputUnit | Mbps | Mbps |
| virtualDeviceName | myCiscoSubSR | myCiscoByolSR |
| orderingContact | subuser01 | subuser01 |
| accountNumber | 1234567 | 1234567 |
| action | CREATE | CREATE |
| sshUsername | myTest | myTest |
| sshPassword | myProjPass! | myProjPass! |
| addtionalBandwidth | 100 | 100 |
| purchaseOrderNumber | 888888 | 888888 |
| deviceManagementType | EQUINIX-CONFIGURED | EQUINIX-CONFIGURED |
| core | 4 | 4 |
| interfaceCount | 24 | 24 |
| channelPartner | SDCI | SDCI |
Handling Device Failures
1) Device provisioning failures
Device provisioning takes time, depending on the vendor selected. If your virtual device fails to provision within an hour and is still stuck in PROVISIONING, WAITING_FOR_PRIMARY, WAITING_FOR_SECONDARY or FAILED status, you should open a support ticket to address the issue.
2) Device recovery failure
If your device shuts down for any reason, an automatic recovery will be initiated, and your device will move to RECOVERY_INIT status. If the recovery goes through successfully, the device will move back to PROVISIONED status. If the device fails to recover, you may want to create a support ticket to help resolve the issue.
| Virtual device "status" | Description |
|---|---|
| RECOVERY_INIT | The device is recovering after a failure. |
| FAILED | Device recovery failed. |
| PROVISIONED | The device is ready to use. |
Handling Licensing Failures
1) License registration failures
If your device fails to register successfully for a subscription license, you should open a support ticket with Equinix. However, if your device fails to register successfully for BYOL (bring your own license), please make sure your license file or token is valid. Also, you may want to retry uploading the license using Equinix APIs.
a) If you have already created a virtual device, use the Post License {uuid} API to retry posting a license file. You can also use this API to renew a license that is about to expire. You must upload two files in case you have a redundant device.
b) If you have a Cisco device, you can use the Update License API to update a license token/code/ID. You may use the same or two different tokens in case you have a redundant device.
2) License de-provisioning failures
When you de-provision a device, your license will move to "N/A" status under most circumstances. However, if a third-party is involved in license de-registration, your license may go through UNREGISTERING, UNREGISTERED or UNREGISTRATION_FAILED states. If the license fails to de-register, Equinix will look into it.