Skip to main content
Index

Launch Equinix-Configured Device

 

To create a virtual device, you must have the following information:

 

1) Which virtual device type (deviceTypeCode) you want, the number of cores (core) and the software type (packageCode and version) you need, and the location where you want your virtual device (metroCode). You may choose any available zone in the metro of your choice if the metro offers zones.

2) Equinix account number. Your account must be in the Active or Pending status. 

3) License option (licenseMode). If you opt for a subscription license, Equinix will manage and charge monthly. We offer subscription licenses for Cisco, Juniper, Palo Alto, and Fortinet devices. If you want to bring your own license, please upload the license file/token from your vendor.

 

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.

 

Refer to the Network Edge deployment guide for pre-requisites to bring your own license option (BYOL) and for other additional services like BGP peering and VPN configuration.

Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating a Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Network Edge, 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. You may choose to have the default or the maximum interface count for your device.  

If the metro of your choice has zones, you may specify any available zone (zoneCode). To check out all the availability zones, call Get Metro.

 

 

2b) Get account

 

Call Get account 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 BYOL (bring your own license), you must upload a license file or a license code/token/ID, depending on what your vendor offers.

 

   For Cisco and Palo Alto devices, you must provide a license token at the time you create a device if you wish to BYOL.

   For Juniper and Fortinet devices, you must upload a license file 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)

To bring your own license (BYOL) for a Juniper or a Fortinet device, use the Post a license file before creating a device API to upload a license file. You will get a file ID that you can use to create a virtual device. In case you have an HA Juniper device that has a secondary device for high availability, you can use the same fileId for both the primary and secondary devices. 

For a Cisco or Palo Alto device, enter a license token in the create device payload to BYOL (bring your own license). 

 

3b) Posting a license after creating a device (BYOL)

If your license did not register (REGISTRATION_FAILED) although your device is provisioned, use the Post a license file after creating a device API to re-post a license file. You must upload two files in case you have an HA device that has a secondary device for high availability. 

 

3c) Post a license code/token/ID

If you have a Cisco or a Palo Alto device, you can use the Post a license code/token/ID  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 an HA device that has a secondary device for high availability. 

Step 4: Create Virtual Device

POST /ne/v1/device

 Method  POST
 URL or End Point  /ne/v1/device
 Headers  Authorization token, Content-Type
 Query Parameters  draft, draftUUID
 Body Parameters

additionalBandwidth, deviceTypeCode, hostNamePrefix, licenseFileId, licenseMode, licenseToken, metroCode, notifications[...], packageCode, version, termLength, throughput, throughputUnit, virtualDeviceName, orderingContact, aclTemplateUuid, zoneCode, accountNumber, accountReferenceId, purchaseOrderNumber, interfaceCount, deviceManagementType, core, secondary {accountNumber, accountReferenceId, additionalBandwidth, licenseFileId, licenseToken, metroCode, notifications[...], aclTemplateUuid, zoneCode, sshUsers[{sshUserUuid, action, sshUsername, sshPassword}], virtualDeviceName, hostNamePrefix"}

 

To create an HA (high availability) device, 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 for an HA device, you may or may not need two different license files or tokens, depending on your choice of vendor.

 

   a) For a Cisco HA device, you may use the same license token for the primary and secondary devices. 

   b) For a Juniper HA device, you may or may not use the same license file. 

   c) For a Palo Alto HA device, you may or may not use the same license token.

 

3) If you are a reseller trying to create an HA 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 key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

A sample curl request to create a virtual device with NO secondary device (non-HA).

 

curl -X

POST "https://api.equinix.com/ne/v1/device?draft=false"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '{

  "throughput":500,

  "throughputUnit":"Mbps",

  "metroCode":"DC",

  "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"}],

  "aclTemplateUuid":"39289456-a63e-47d4-927c-5161cfb77500",

  "purchaseOrderNumber":"234567",

  "accountNumber":"2252619",

  "additionalBandwidth":"100",

  "deviceManagementType": "EQUINIX-CONFIGURED",    

  "core": 4,

  "interfaceCount": 24

}'

 

A sample curl request to create an HA virtual device that has a secondary device for high availability (HA). 

 

curl -X

POST "https://api.equinix.com/ne/v1/device?draft=false"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '{

  "throughput":500,

  "throughputUnit":"Mbps",

  "metroCode":"DC",

  "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"}],

  "aclTemplateUuid":"39289456-a63e-47d4-927c-5161cfb77500",

  "purchaseOrderNumber":"234567",

  "accountNumber":"2252619",

  "deviceManagementType": "EQUINIX-CONFIGURED",    

  "core": 4,

  "interfaceCount": 24,

  "secondary":

  {"metroCode":"DC",

  "notifications":["test@gmail.com"],

  "virtualDeviceName":"Test-device-006-SROY - secondary",

  "hostNamePrefix":"SROY-SEC",

  "additionalBandwidth":"200",

  "sshUsers":[{"action":"CREATE","sshUsername":"mekana12","sshPassword":"Mekana123"},{"action":"REUSE","sshUserUuid":"72902689-dff7-437d-8832-4bc8f3495252"},

  {"action":"REUSE","sshUserUuid":"a394dee9-d71d-4446-9210-c948cdd18a4b"}],

  "aclTemplateUuid":"39289456-a63e-47d4-927c-5161cfb77500",

  "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).
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 prefix. This gets included as part of an FQDN that ensures the device is reachable from the approved sources if desired. 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. Also, it should be a minimum of 2 and a maximum of 10 characters long. 
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. For Juniper HA devices, you may use the same license file for both the devices. 
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. For Palo Alto HA devices, you may provide either one or two different tokens. 
metroCode Yes string SV   Metro code. You may choose two different metros for your HA device. 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 an HA device with a secondary device for high availability. 
termLength No integer 24   Billing term length in months.
throughput No integer 500   Throughput. Mandatory for most devices, e.g. CSR1000V. Do not send this parameter for Fortinet or Palo Alto devices.
throughputUnit No string Mbps   Throughput unit. Mandatory for most devices, e.g. CSR1000V. Do not send this parameter for Fortinet or Palo Alto devices.
aclTemplateUuid No string 39289456-a63e-47d4-927c-5161cfb77500   The template Id of a device ACL template created using POST Device ACL Template.  
zoneCode No string Zone1   If your metro has zones, you may specify the zone in which you want your virtual device.
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 an HA 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   Whether you want the default number or the maximum number of interfaces available on the device.
secondary No object secondary{}   Object containing the optional HA device details to create a secondary device for high availability. 
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

 

Sample response for a non-HA device.

 

{
    "uuid": "74d8c6b6-3153-4271-9f0e-45bdc7094dec"
}

 

Sample response for a virtual device with an additional secondary device for high availability.

 

{
    "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 (HA).

 

 

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 requested a secondary device for high availability (HA). 
WAITING_FOR_SECONDARY The primary device is ready, but the secondary is not. This state may appear only if you have requested a secondary device for high availability (HA). 
FAILED The device creation failed. 
PROVISIONED The device is ready. 

 

 

When end-users delete a device using the DELETE virtual device API,  the device transitions through the following states within the Equinix infrastructure. 

 

Virtual device "status" under /ne/v1/device/{uuid} Description
DEPROVISIONING Equinix accepted your request to delete a virtual device. 
DEPROVISIONED The device is deprovisioned/deleted. 

Sample Payloads

Parameter Name CSR1000V subscription CSR1000V BYOL Juniper Juniper Palo Alto Palo Alto Fortinet Fortinet
deviceTypeCode CSR1000V CSR1000V VSRX VSRX PA-VM PA-VM FG-VM FG-VM
hostNamePrefix myHost123 myHost123 myHost123 myHost123 myHost123 myHost123 myHost123 myHost123
licenseMode Sub BYOL BYOL Sub BYOL Sub BYOL Sub
licenseToken  
ZTRjZTdlYmYtZjQ3
    6789992      
licenseFileId     cf92ee6f-286f-496e-b4a1-7b4d1802109e       cf92ee6f-286f-496e-b4a1-7b4d1802109e  
notifications test@equinix.com test@equinix.com test@equinix.com test@equinix.com test@equinix.com test@equinix.com test@equinix.com test@equinix.com
metroCode DC DC DC DC DC DC DC DC
acl 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32
packageCode SEC SEC STD STD VM100 VM100 VM02 VM02
version 16.09.03 16.09.03

19.1R1.6

19.1R1.6

9.0.0

9.0.0

6.0.4 6.0.4
throughput 500 500 1 1        
throughputUnit Mbps Mbps Gbps Gbps        
virtualDeviceName myCiscoSubSR myCiscoByolSR myJuniperSR myJuniperSR myPaloAltoSR myPaloAltoSR myFortinetSR myFortinetSR
orderingContact subuser01 subuser01 subuser01 subuser01 subuser01 subuser01 subuser01 subuser01
accountNumber 1234567 1234567 1234567 123456 1234567 123456 1234567 1234567
action CREATE CREATE CREATE CREATE CREATE CREATE CREATE CREATE
sshUsername myTest myTest myTest myTest myTest myTest myTest myTest
sshPassword myProjPass! myProjPass! myProjPass! myProjPass! myProjPass! myProjPass! myProjPass! myProjPass!
addtionalBandwidth 100 100 100 100 100 100 100 100
purchaseOrderNumber 888888 888888 888888 888888 888888 888888 888888 888888
deviceManagementType EQUINIX-CONFIGURED EQUINIX-CONFIGURED EQUINIX-CONFIGURED EQUINIX-CONFIGURED EQUINIX-CONFIGURED EQUINIX-CONFIGURED EQUINIX-CONFIGURED EQUINIX-CONFIGURED
core 4 4 5 5 4 4 4 4
interfaceManagementCount 24 24 16 16 23 23 9 9

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 a 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 a license file after creating a device  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 an HA device that has a secondary device for high availability. 

 

              b) If you have a Cisco or a Palo Alto device, you can use the Post a license code/token/ID  API to update a license token/code/ID. You may use the same or two different tokens in case you have an HA device that has a secondary device for high availability. 

 

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.