Skip to main content
Index

Launch Self-Configured Device

Launch Virtual Device

A customer will have more control over a Self-Configured device compared to an Equinix-Configured device. The Self-Configured option can be thought of as an IaaS deployment, whereas the Equinix-Configured option is PaaS. To create a Self-Configured device you must do the following:

 

1) Know 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). 

 

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

 

3) If you wish to upload a license token or file, check out Step 3

 

4) Set up accessibility:

     a)  Have your SSH Public Key ready to upload. The keyName must be an existing keyName associated with an existing keyValue. To set up a new keyName and keyValue pair, call Create Public Key

     b) To have access control, you may either use an existing ACL template or create a new ACL template by calling the Create ACL Template method. Use the unique Id of the new/existing template in the payload when creating your device. 

 

If you have all the necessary information, skip ahead to Step 4 and create a device. Otherwise, follow the steps:

 

To save a device draft, you must provide deviceTypeCode, accountNumber/accountReferenceId, and metroCode.

 

Refer to Creating a Self-Configured Edge Device for more details. 

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 self-configured 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), vendors of devices, the available number of cores (core) and software packages (packageCode and version), and all possible throughput options.  

 

You may choose to have the default or the maximum interface count for your device. Also, you may select any available device interface as sshInterfaceId. Otherwise, Equinix will choose the first available interface.

 

2b) Get accounts

 

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, go here.

 

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

As of now, we only offer a bring your own licensing (BYOL) option. You may upload a license file or a license code/token/ID, depending on what your vendor offers. 

   Cisco and Palo Alto provide license tokens. Enter a license token in the create device payload to bring your own license (BYOL). 

   Juniper and Fortinet provide license files. To bring your own license (BYOL) for a Juniper or a Fortinet device, use the Post License 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 a redundant Juniper device, you can use the same fileId for both the primary and secondary devices. 

Log in to the device to check your license status. 

Step 4: Create Self-Configured 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, hostNamePrefix, metroCode, zoneCode,

 notifications[...], packageCode, version, termLength,

 throughput, throughputUnit, virtualDeviceName, orderingContact, aclTemplateUuid, accountNumber, accountReferenceId, 

 purchaseOrderNumber, interfaceCount, deviceManagementType, core, userPublicKey { username, keyName}, sshInterfaceId, licenseMode, licenseToken, licenseFileId, secondary   {accountNumber, accountReferenceId, additionalBandwidth, metroCode, zoneCode, notifications[...], aclTemplateUuid,

virtualDeviceName, hostNamePrefix, sshInterfaceId, licenseMode, licenseToken, licenseFileId"}

 

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) 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 key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request to create a self-configured device.

 

curl -X

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

{

    "metroCode": "SV",

    "deviceTypeCode": "VSRX",

    "termLength": "1",

    "licenseMode": "BYOL",

    "packageCode": "STD",

    "virtualDeviceName": "Test-device-001-SROY",

    "notifications": [

        "test@equinix.com"

    ],

    "hostNamePrefix": "TC12",

    "aclTemplateUuid": 

        "39289456-a63e-47d4-927c-5161cfb77500"

    ,

    "accountNumber": "200541",

    "version": "18.4R2-S1.4",

    "interfaceCount": 10,

    "deviceManagementType": "SELF-CONFIGURED",

    "core": 5,

    "userPublicKey": {

        "username": "userName",

        "keyName": "keyName"

    },

    "additionalBandwidth": "100"

}

'

 

The following screenshot shows 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": "1",

    "throughputUnit": "Gbps",

    "metroCode": "DC",

    "deviceTypeCode": "CSR1000V",

    "termLength": "1",

    "licenseMode": "BYOL",

    "packageCode": "AX",

    "virtualDeviceName": "Test-device-001-SROY",

    "notifications": [

        "test@equinix.com"

    ],

    "hostNamePrefix": "TC01",

    "aclTemplateUuid": 

                "39289456-a63e-47d4-927c-5161cfb77500"

        

    ,

    "accountNumber": "200541",

    "version": "16.09.05",

    "interfaceCount": 10,

    "deviceManagementType": "SELF-CONFIGURED",

    "core": 4,

    "userPublicKey": {

        "username": "sroy",

        "keyName": "keyName"

    },

    "sshInterfaceId": "3",

    "secondary": {

        "metroCode": "DC",

        "hostNamePrefix": "TC02",

        "notifications": [

            "test@equinix.com"

        ],

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

        "additionalBandwidth": "100",

        "aclTemplateUuid": 

        

                    "49289456-a63e-47d4-927c-5161cfb77501"

               

        ,

        "accountNumber": "200541",

        "sshInterfaceId": "4"

    },

    "additionalBandwidth": "100"

}

'

 

The description of the query parameters is as follows:

 

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 will not be saved for drafts. Also, this API will not do access-control list validation when you save a draft. 
draftUuid No string ec68e425-f973-452e-a866-76be5844d0ba   To create a device from a draft you saved earlier, provide the unique Id of the draft (draftUuid). 

 

The description of the body parameters is as follows:

 

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   Hostname prefix. This gets included as part of an FQDN that ensures the device is reachable from 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. 
licenseMode Yes string BYOL BYOL License type. At this time, BYOL is the only available option for self-configured devices.
licenseToken No string 4567890   License token.
licenseFileId No string 4cfb5675-5c3f-4275-adba-0c9e3c26c96b   You must first upload the license file using the Post License method. 
metroCode Yes string SV   Metro code. You may provide two different metros if you are creating a redundant 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.
zoneCode No string Zone1   You may select any availability zone if the metro of your choice offers availability zones.
notifications Yes array test1@example.com   Email addresses for device life-cycle notification. We need a minimum of 1 and no more than 5 email addresses. You may have a different notification list for your secondary device if you are creating a redundant device. 
packageCode Yes string VM100   Software package code. 
version Yes string 16.09.03   Version.
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. 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 49289456-a63e-47d4-927c-5161cfb77501   The template id of a device ACL template created using Create ACL Template.
purchaseOrderNumber No string 3456789   Purchase order number. Optional field that customers can use to track this device creation to their own 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 SELF-CONFIGURED   Whether the device is managed by Equinix or self-configured. This use case addresses SELF-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.
userPublicKey Yes object

 "userPublicKey": {

        "username": "sroy",

        "keyName": "keyName"

    }

  An object containing the username and keyName. 
userPublicKey.username Yes string sroy   Username.
userPublicKey.keyName Yes string keyName   Key name. 
sshIntefaceId No integer 3   You may specify any available device interface as the sshInterfaceId. 
secondary No object secondary{}   The object containing the optional secondary device details to create a redundant device. 

 

Sample response for a single device.

202: Request accepted.

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

 

Sample response for a redundant device.

202: Request accepted.

{
    "uuid": "74d8c6b6-3153-4271-9f0e-45bdc7094dec",
    "secondaryUuid": "de5cf79b-3d16-4ccd-841b-3b68ecda2142"
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
uuid string b43ba509-a7d9-4334-8dee-dc4f29bf2e77 Unique identifier of the self-configured virtual device.
secondaryUuid string 92c2e49d-2c35-432d-a9af-016920bef70c Unique identifier of the secondary self-configured virtual device.

 

 

When a device is created, the self-configured 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. 

 

Virtual device "status"  Description
INITIALIZING Equinix is in the process of reserving resources and creating the device.
PROVISIONING The device is booting.
PENDING_ORDER The order has come to NE from Siebel. Customers need to log in to the NE portal and submit the order.
PENDING_SIGNATURE The customer has signed up for the offline acceptance of NE terms but has not yet accepted the terms.
CANCEL_ORDER The order from Siebel to NE is canceled. 
WAITING_FOR_PRIMARY The secondary device is ready but the primary is not. This state might 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 might 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/device/{uuid} Description
DEPROVISIONING Equinix accepted the customer's request to delete a virtual device. 
DEPROVISIONED The device is de-provisioned/deleted. 

Sample Payloads

Parameter Name CSR1000V Juniper Palo Alto Fortinet
deviceTypeCode CSR1000V VSRX PA-VM FG-VM
hostNamePrefix myHost123 myHost123 myHost123 myHost123
licenseMode BYOL BYOL BYOL BYOL
notifications test@equinix.com test@equinix.com test@equinix.com test@equinix.com
metroCode DC DC DC DC
aclTemplateUuid 39289456-a63e-47d4-927c-5161cfb77500 39289456-a63e-47d4-927c-5161cfb77500 39289456-a63e-47d4-927c-5161cfb77500 39289456-a63e-47d4-927c-5161cfb77500
packageCode SEC STD VM100 VM02
version 16.09.03

19.1R1.6

9.0.0

6.0.4
throughput 500 1    
throughputUnit Mbps Gbps    
virtualDeviceName myCiscoByolSR myJuniperSR myPaloAltoSR myFortinetSR
orderingContact subuser01 subuser01 subuser01 subuser01
accountNumber 1234567 1234567 1234567 1234567
addtionalBandwidth 100 100 100 100
purchaseOrderNumber 888888 888888 888888 888888
deviceManagementType SELF-CONFIGURED SELF-CONFIGURED SELF-CONFIGURED SELF-CONFIGURED
core 4 5 4 4
interfaceCount 24 16 23 9
userPublicKey.username test test test test
userPublicKey.keyName keyName keyName keyName keyName
sshInterfaceId 3 3 3 3