Skip to main content
Index

Launch SDWAN Device

SDWAN Device

 

To create SDWAN devices, you must have the following information:

 

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

 

2) Equinix account number with the account status in Active or Pending state. 

 

3) The process to bring your own license (BYOL) from your vendor. Check Step 3 for detailed instructions. 

 

4) You must have the necessary vendor-specific parameters for your device. Check Step 4 for detailed instructions. 

 

4) ACLs: Please include the aclTemplateUuid of a template you have created earlier using POST Device ACL Template.

    

   a) For Cisco SDWAN, the ACL template must have the IP addresses of vBond, vManage, and vSmart servers, so they have access to the device. 

 

Refer to Provisioning Cisco cEdge SD-WAN for details.

   

   b) For CloudGenix, the ACL template must include IP addresses from CloudGenix portal, so they have access to the device. 

 

   c) For Versa devices, the ACL template must include the IP addresses provided by Versa. This is not in CIDR format. 

 

   d) For Fortinet devices, the ACL template must include the SDWAN controller IPs, so they have access to the device.

 

   e) For Velocloud, the ACL template must include the IP addresses associated with the controllerFqdn. The controllerFqdn is a vendor-specific parameter necessary for Velocloud devices.  

 

If you have all the necessary information, skip ahead to Step 5 and create SDWAN devices. Otherwise, follow the steps:

 

If you do not have all the necessary information, you can still save as a draft. You must provide deviceTypeCode, accountNumber/accountReferenceId, and metroCode to save a draft.

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 SDWAN devices you can launch on the NE platform. You will learn about metros (metroCode) where these devices are available, the available number of cores (core) and software packages (packageCode & 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.

 

You may skip this step if you already know which device you want.

 

2b) Get account

Check your account number (or acountReferenceId) and status in the metro where you want a virtual device by calling Get account API. 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 an SDWAN device for your customer.

 

You may skip this step if you already know your account number (or accountReferenceId) and status.  

Step 3: Configure a License

For now, BYOL (bring your own license) is the only licensing option available for SD-WAN devices and the process to BYOL is unique to every vendor. 

 

a) To configure a license for a CISCO SD-WAN device, you must do the following:

  1) Generate a bootstrap file on Cisco vManage platform. 

  2) Upload the Cisco bootstrap file on Equinix platform by calling POST a license before creating a virtual device (BYOL). You'll get a fileId that you can use to create a virtual SD-WAN device. 

 

b) To configure a license for a CloudGenix device, you must do the following: 

   1) Generate a license key (ION key) and license secret (Secret key) on CloudGenix platform.

   2) Input the license key (ION key) and secret (Secret key) when calling Equinix create device API to create a CloudGenix SDWAN device. 

 

c) To configure a license for a Fortinet SD-WAN device, you must do the following:

   1) Generate a license file on Fortinet portal.

   2) Upload the license file file on Equinix portal  by calling POST a license before creating a virtual device (BYOL). You'll get a fileId that you can use to create a virtual SDWAN device. 

 

d) To configure a Versa device, please create a vNF device template on Versa director and note the serial number.

 

e) You do not need a license file to configure a Silver Peak device on the Network Edge platform. 

Step 4: Vendor-specific Parameters

Each SD-WAN vendor requires its own set of parameters other than the common parameters listed as part of POST API definition in Step 5. Please check the parameters of your vendor and pass the parameters in the vendorConfig{} object when creating a new device in Step 5. 

 

a) Cisco: CSRSDWAN

Cisco vendorConfig{ } parameters Mandatory Type Example Possible Values Description
siteId Yes string 12345   Site Id. Mandatory for Cisco SDWAN devices. A siteId is a particular physical location within the Viptela overlay network, such as a branch office, or a campus.
systemIpAddress Yes string 192.168.1.5   System IP address. Mandatory for Cisco SDWAN devices. Each vEdge router and vSmart controller is assigned a system IP address. It should be in decimal four-part dotted notation, just like IPv4 address. 

 

 

b) CloudGenix: CGENIXSDWAN

CloudGenix vendorConfig{ } parameters Mandatory Type Example Possible Values Description
licenseKey (ION key) Yes string 1404-991d81bb-2567-43e5-a14c-1493ace58046   License key (ION key). Mandatory for CloudGenix devices.
licenseSecret (Secret key) Yes string ec68e425-f973-452e-a866-76be5844d0ba   License secret (Secret key). Mandatory for CloudGenix devices. 

 

 

c) Versa: VERSA_SDWAN

Versa vendorConfig{ } parameters Mandatory Type Example Possible Values Description
localId Yes string SDWAN-Branch@Versa.com   Email address of the branch location. 
remoteId Yes string Controller-01-staging@Versa.com   Email address of the controller side. 
serialNumber Yes string 12345   The customer selects a serial number when setting up the device template on Versa director. Versa post-staging device serial number on Versa director should match this input.
controller1 Yes string 54.219.248.29   Ip address of the SD-WAN controller1. 
controller2 Yes string 54.177.220.115   Ip address of the SD-WAN controller2. 

 

 

d) FortiGate : FG-SDWAN *

FortiGate vendorConfig{ } parameters Mandatory Type Example Possible Values Description
adminPassword Yes string 5678909   Password.
controller1 Yes string 1.1.1.1   System IP address. Mandatory for FortiGate SDWAN devices. 

*FortiGate SD-WAN devices also need hostNamePrefix but it is not part of vendorConfig object, just passed as a parameter along with others like deviceTypeCode, accountNumber etc.

 

 

d) Velocloud : VELOCLOUD-SDWAN 

Velocloud vendorConfig{ } parameters Mandatory Type Example Possible Values Description
activationKey Yes string GJUK-JM2X-59BJ-2TDJ   Activation key. Available on Velocloud Orchestration Portal.
controllerFqdn Yes string demo.velocloud.net   Velocloud Gateway. In the list of ACLs for the device, please provide the IP addresses associated with the controllerFqdn. 
rootPassword No string myPassw0rd!   CLI password for the device.

 

d) Silver Peak: EDGECONNECT-SDWAN

Silver Peak vendorConfig{ } parameters Mandatory Type Example Possible Values Description
accountName Yes string accountName   The name of the account.
hostname Yes string hostName   The host name.
accountKey Yes string accountKey   The account key.
applianceTag No string applianceTag   The appliance tag.

Step 5: Create SDWAN Devices

POST /ne/v1/device

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

 additionalBandwidth, deviceTypeCode, licenseFileId, licenseMode, metroCode, 

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

 throughput, throughputUnit, vendorConfig{ }, virtualDeviceName, orderingContact, aclTemplateUuid, accountNumber, accountReferenceId, 

 purchaseOrderNumber, deviceManagementType, interfaceCount, core, zoneCode, secondary   {accountNumber, accountReferenceId, aclTemplateUuid, additionalBandwidth, licenseFileId,

 metroCode, notifications[...], vendorConfig{ }, virtualDeviceName, zoneCode}}

 

 

If you want to create an HA device that has a secondary device for high availability, please do the following:

      1) set vendorConfig parameters of the optional secondary object. Click here to know your vendorConfig parameters. 

  1. provide two licenseFileIds for Cisco SDWAN in the request body payload
  2. provide two licenseKeys (ION keys) and license secrets (Secret keys) for CloudGenix in the request body payload
  3. provide two activationKeys for veloCloud HA SDWAN device. 

      2) you may have a different ACL template, account number, additionalBandwidth, metroCode, and notifications for your secondary device.

      3) If you are a reseller trying to create an HA device for your customer, please make sure that 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 Cisco SDWAN device with NO secondary device (non-HA).

 

curl -X POST 
  https://api.equinix.com/ne/v1/device?draft=false
  -H 'Authorization: Bearer dbFb0zo203fxyRpBrGd6wAX3IGSR' 
  -H 'Content-Type: application/json' 
  -d '
{
    "throughput": 1,
    "throughputUnit": "Gbps",
    "metroCode": "SV",
    "deviceTypeCode": "CSRSDWAN",
    "termLength": "1",
    "licenseMode": "BYOL",
    "packageCode": "ESSENTIALS",

    "version": "16.12.1e",
    "virtualDeviceName": "API-SROY-SD101",
    "notifications": [
        "test@equinix.com"
    ],
    "vendorConfig": {"systemIpAddress": "1.1.1.1", "siteId": "5"},
    "aclTemplateUuid": 
        "39289456-a63e-47d4-927c-5161cfb77500",
    "licenseFileId": "abc388de-7e48-4521-9390-f8eb3474b74f",
    "accountNumber": "5710199",
    "additionalBandwidth": "300",

    "deviceManagementType": "SELF-CONFIGURED",

    "core": 4,

    "interfaceCount": 24
}
'

 

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

 

curl -X POST 
https://api.equinix.com/ne/v1/device?draft=false
-H 'Authorization: Bearer dbFb0zo203fxyRpBrGd6wAX3IGSR' 
-H 'Content-Type: application/json' 

-d '

{

 "throughput": 1,

    "throughputUnit": "Gbps",

    "metroCode": "SV",

    "deviceTypeCode": "CSRSDWAN",

    "termLength": "1",

    "licenseMode": "BYOL",

    "packageCode": "ESSENTIALS",

    "version": "16.12.1e",

    "virtualDeviceName": "API SROY-1",

    "notifications": [

        "test@equinix.com"

    ],

    "vendorConfig": {"systemIpAddress": "1.1.1.1", "siteId": "5"},

    "aclTemplateUuid": 

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

    "licenseFileId": "abc388de-7e48-4521-9390-f8eb3474b74f",

    "accountNumber": "5710199",

    "additionalBandwidth": "300",   

    "deviceManagementType": "SELF-CONFIGURED",

    "core":4

    "interfaceCount": 24,

    "secondary":{

    "metroCode":"SV",

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

    "virtualDeviceName":"API SROY-1-sec",

    "vendorConfig": {"systemIpAddress": "1.1.1.1", "siteId": "12345"},

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

    "licenseFileId":"abc388de-7e48-4521-9390-f8eb3474b74f",

    "accountNumber":"5710199"

    }

}

'

 

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. 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 that 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
additionalBandwidth   integer 100   Additional bandwidth. You may have a different additional bandwidth for your secondary device in case you have an HA device. You cannot have additionalBandwidth for CloudGenix devices.
deviceTypeCode Yes string CSRSDWAN

CSRSDWAN, CGENIXSDWAN

Virtual device type (device type code). 
licenseFileId   string 6651aef5-e738-411f-8675-5f6b7b9cd429   License file Id. Mandatory for Cisco SDWAN devices. 
licenseMode Yes string BYOL   License type. For now, the only available option is BYOL (bring your own license).
metroCode Yes string SV   Metro code. You may provide 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 [test@equinix.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 HA device that has a secondary device for high availability. 
packageCode Yes string ESSENTIALS   Software package code. 
version Yes string 16.12.1e   Version.
termLength Yes integer 24   Billing term length in months. Default = 1 month.
throughput   integer 500   Throughput. Mandatory for Cisco SDWAN. You cannot specify throughput for CloudGenix devices. 
throughputUnit   string Mbps   Throughput unit. Mandatory for Cisco SDWAN. You cannot specify throughputUnit for CloudGenix devices. 
vendorConfig Yes object "vendorConfig": {"systemIpAddress": "1.1.1.1", "siteId": "12345"}   Vendor parameters. To check the parameters of your vendor, go to Step 4.
virtualDeviceName Yes string CiscoSTROY   Virtual device name for identification. This should be minimum 3 and maximum 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. 
aclTemplateUuid Yes string 39289456-a63e-47d4-927c-5161cfb77500   The template Id of a device ACL template created using Post Device ACL template.
accountNumber   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   string     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. 
purchaseOrderNumber   string 3456789   Purchase order number. Optional field that customers can use to track this device creation to their own purchase order number. 
core Yes integer 4   The number of cores you want for your device.
interfaceCount   integer 24   Whether you want the default or the maximum number of available interfaces.
deviceManagementType Yes string SELF-CONFIGURED   SDWAN devices are self-configured.
zoneCode   string Zone1   If your metro has zones, you may specify the zone in which you want your device.
secondary   object secondary{}   An object containing the optional HA device details to create a secondary device for high availability. 

 

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

 

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 SDWAN virtual device.
secondaryUUID string 92c2e49d-2c35-432d-a9af-016920bef70c Unique identifier of the secondary SDWAN virtual device (HA).

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 

When an SDWAN 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. Once your device is provisioned and the license is applied, you can create connections to cloud service providers.

 

Virtual device states Description
INITIALIZING Equinix is in the process of reserving resources and creating the device.
PENDING_ACCOUNT Customer's account is not approved. The device creation will continue once the account gets approved.
PROVISIONING 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 might 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 might appear only if you have requested a secondary device for high availability (HA). 
FAILED Device creation failed. 
PROVISIONED Device is ready. 
DEPROVISIONING Equinix accepted customer's request to delete virtual device. 
DEPROVISIONED Device is deprovisioned/deleted. 

 

 

 

When an end-user deletes a device using the Delete virtual device API,  the device transitions through the following states within the Equinix infrastructure. 

 

status Description
DEPROVISIONING Equinix accepted customer's request to delete virtual device. 
DEPROVISIONED Device is deprovisioned/deleted. 

Sample Payloads for Specific Devices

Parameter Name Cisco SD-WAN CloudGenix SD-WAN Versa SD-WAN FortiGate SD-WAN Velocloud SD-WAN SilverPeak SD-WAN
deviceTypeCode CSRSDWAN CGENIXSDWAN VERSA_SDWAN FG-SDWAN VELOCLOUD-SDWAN EDGECONNECT-SDWAN
licenseMode BYOL BYOL BYOL BYOL BYOL BYOL
licenseFileId cf92ee6f-286f-496e-b4a1-7b4d1802109e     5ffb2450-7a0e-4f05-bfa6-e2245ca12846    
notifications test@equinix.com test@equinix.com test@equinix.com test@equinix.com test@equinix.com test@equinix.com
metroCode DC DC DC SV DC DC
aclTemplateUuid 39289456-a63e-47d4-927c-5161cfb77500 39289456-a63e-47d4-927c-5161cfb77500 39289456-a63e-47d4-927c-5161cfb77500 39289456-a63e-47d4-927c-5161cfb77500 39289456-a63e-47d4-927c-5161cfb77500 39289456-a63e-47d4-927c-5161cfb77500
packageCode PREMIER 7108V FLEX_VNF_6 VM08 VeloCloud-4 EC-M
version 16.12.3 5.1.1-b41

16.1R2S8

6.0.4 3.3.0 8.3.1
throughput 500          
throughputUnit Mbps          
virtualDeviceName mySDWANSxyz myCGSDWANxyz myVersaSDWANxyz myFGsroySDWAN myVeloSDWAN mySilverPeak
orderingContact subuser01 subuser01 subuser01 subuser01 subuser01 subuser01
accountNumber 1234567 1234567 1234567 1234567 123456 123456
addtionalBandwidth 100 100 100 100 100 100
purchaseOrderNumber 888888 888888 88888 888888 88888 88888
interfaceCount 24 10 16 9 8 10
core 4 4 8 8 8 4
deviceManagementType SELF-CONFIGURED SELF-CONFIGURED SELF-CONFIGURED SELF-CONFIGURED SELF-CONFIGURED SELF-CONFIGURED
siteId 456          
systemIpAddress 1.1.1.1          
licenseKey   1404-991d81bb-2567-43e5-a14c-1493ace58046        
licenseSecret   d29dceeef2d2b494c9eb76937a361890786e609d        
termLength 12 12 12 12    
localId     SDWAN-Branch@Versa.com      
remoteId     Controller-01-staging@Versa.com      
serialNumber     12345      
controller1     54.219.248.29 1.1.1.1    
controller2     54.177.220.115      
adminPassword       5678909    
hostNamePrefix       TC16    
activationKey         GJUK-JM2X-59BJ-2TDJ  
controllerFqdn         demo.velocloud.net  
rootPassword         myPassw0rd!  
accountName           myAccountName
hostName           myHostName
accountKey           myAccountKey
applianceTag           myApplianceTag