Launch SDWAN Device
Here are the steps to create SD-WAN devices using APIs:
1) Find out the following information
- the SD-WAN device (deviceTypeCode) you want
- the number of cores (core) you want
- the software type (packageCode & version) you need
- the location where you want your SD-WAN device (metroCode).
2) Equinix account number with the account status in Active or Pending state.
3) At this time, we only offer the bring your own license (BYOL) option for most SD-WAN devices. Check Step 3 to learn the process to bring your own license (BYOL) from your vendor.
Note: Sub-customers cannot choose the subscription licensing option. Even resellers creating devices for sub-customers can only choose the BYOL option.
4) You must have the necessary vendor-specific parameters for your device. Check Step 4 for detailed instructions.
5) ACLs: Please include the unique Id of a template you have created earlier using Create ACL Template. An ACL template is mandatory for all SD-WAN devices.
a) For Cisco SD-WAN, the ACL template must have the IP addresses of vBond, vManage, and vSmart servers, so the servers have access to the device.
See Provisioning Cisco cEdge SD-WAN for details.
b) For CloudGenix, the ACL template must include IP addresses from the CloudGenix portal, so the CloudGenix servers 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 SD-WAN controller IPs.
e) For VMware, the ACL template must include the IP addresses associated with the controllerFqdn. The controllerFqdn is a vendor-specific parameter necessary for VMware devices.
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 5 and create SD-WAN devices. Otherwise, follow the steps:
If you do not have all the necessary information, you can still save the information as a draft. You must provide a deviceTypeCode, an accountNumber/accountReferenceId, and a metroCode to save a draft.
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 the SD-WAN 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), the software packages (packageCode & version), and all possible licensing and throughput options.
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 Accounts {metro} 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 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 an SD-WAN 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, bring your own license (BYOL) 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 devices, you must do the following:
1) Generate a bootstrap file on Cisco vManage platform.
2) If you are creating a CSRSDWAN device, upload the Cisco bootstrap file on the Equinix platform by calling Post License File. You'll get a fileId in the response. You can enter the value in the licenseFileId field of the create payload to create a virtual CSRSDWAN device.
If you are creating a C8000V-SDWAN, upload the Cisco bootstrap file by calling Upload File. You'll get a fileUuid in the response. You can enter the value in the day0TextFileId field of the create payload to create a virtual C8000V-SDWAN 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 SD-WAN device.
c) License is not mandatory for Fortinet devices at the time of device creation. If you have a token, enter it in the licenseToken field. To configure a license file for a Fortinet SD-WAN device, do the following:
1) Generate a license file on the Fortinet portal.
2) Upload the license file on the Equinix portal by calling Post License File. You'll get a fileId that you can use to create a virtual SD-WAN 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 an Aruba device on the Network Edge platform.
f) To upload a license for a Juniper SD-WAN, you must do the following:
1) Generate a license file on the Juniper portal.
2) Upload the license file on the Equinix portal by calling Post License File. You'll get a fileId that you can use to create a Juniper SD-WAN device.
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 SD-WAN 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 SD-WAN 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. | |
| hostname | Conditional | string | SR-01 | hostname. Mandatory for C8000V-SDWAN. |
b) CloudGenix: PRISMA-SDWAN
| 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 | ThisPassword9 | Password. This password should be at least 6 characters long and must include an uppercase letter and a number. | |
| controller1 | Yes | string | 1.1.1.1 | System IP address. Mandatory for FortiGate SD-WAN devices. |
*FortiGate SD-WAN devices also need a hostname but it is not part of vendorConfig object, just passed as a parameter along with others like deviceTypeCode, accountNumber, etc.
e) VMware : VELOCLOUD-SDWAN
| VMware vendorConfig{ } parameters | Mandatory | Type | Example | Possible Values | Description |
|---|---|---|---|---|---|
| activationKey | Yes | string | GJUK-JM2X-59BJ-SAMPLE | Activation key. Available on VMware Orchestration Portal. | |
| controllerFqdn | Yes | string | demo.velocloud.net | VMware Gateway. In the list of ACLs for the device, please provide the IP addresses associated with the controllerFqdn. | |
| rootPassword | No | string | TestPassword! | CLI password for the device. |
f) Aruba: EDGECONNECT-SDWAN
| Aruba vendorConfig{ } parameters | Mandatory | Type | Example | Possible Values | Description |
|---|---|---|---|---|---|
| accountName | Yes | string | accountName | The name of the account. | |
| hostname | Yes | string | myhostname1 | Host name for identification. 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 digit. The length should be between 2-30 characters. Exceptions - FTDv 2-14; Aruba 2-24. | |
| accountKey | Yes | string | accountKey | The account key. | |
| applianceTag | No | string | applianceTag | The appliance tag. |
Step 5: Create SD-WAN Devices
| POST /ne/v1/devices | |
|---|---|
| Method | POST |
| URL or End Point | /ne/v1/devices |
| Headers | Authorization, Content-Type |
| Query Parameters | draft, draftUuid |
Download Postman Scripts for exact payloads to create devices. Every device has its own payload, depending on the vendor of the device.
If you want to create a redundant SD-WAN device that has two devices, primary and secondary, do the following:
1) Set vendorConfig parameters of the optional secondary object. Click here to know your vendorConfig parameters.
- provide two licenseFileIds for a Cisco SD-WAN in the request body payload
- provide two licenseKeys (ION keys) and license secrets (Secret keys) for a CloudGenix redundant device in the request body payload
- provide two activationKeys for a VMware redundant SD-WAN 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 a redundant device for your customer, 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 Cisco SD-WAN device with NO secondary device.
curl -X POST
https://api.equinix.com/ne/v1/devices?draft=false
-H 'Authorization: Bearer dbFb0zo203fxyRpBrGd6wAX3IGSR'
-H 'Content-Type: application/json'
-d '
{
"throughput": 1,
"throughputUnit": "Gbps",
"metroCode": "SV",
"agreeOrderTerms": true,
"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"},
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"licenseFileId": "abc388de-7e48-4521-9390-f8eb3474b74f",
"accountNumber": "5710199",
"additionalBandwidth": "300",
"deviceManagementType": "SELF-CONFIGURED",
"core": 4,
"interfaceCount": 24,
"ipType": "DHCP",
"sshInterfaceId": "5",
"channelPartner": "SDCI"
}
'
A sample curl request to create a redundant Cisco SD-WAN device.
curl -X POST
https://api.equinix.com/ne/v1/devices?draft=false
-H 'Authorization: Bearer dbFb0zo203fxyRpBrGd6wAX3IGSR'
-H 'Content-Type: application/json'
-d '
{
"throughput": 1,
"throughputUnit": "Gbps",
"metroCode": "SV",
"deviceTypeCode": "CSRSDWAN",
"agreeOrderTerms": true,
"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"},
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"licenseFileId": "abc388de-7e48-4521-9390-f8eb3474b74f",
"accountNumber": "5710199",
"additionalBandwidth": "300",
"deviceManagementType": "SELF-CONFIGURED",
"core":4
"interfaceCount": 24,
"ipType": "DHCP",
"sshInterfaceId": "5",
"channelPartner": "SDCI",
"secondary":{
"metroCode":"SV",
"notifications":["test@equinix.com"],
"virtualDeviceName":"API SROY-1-sec",
"vendorConfig": {"systemIpAddress": "1.1.1.1", "siteId": "12345"},
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"licenseFileId":"abc388de-7e48-4521-9390-f8eb3474b74f",
"accountNumber":"5710199",
"sshInterfaceId": "5"
}
}
'
| 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). |
| 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 a redundant device. You cannot have additionalBandwidth for CloudGenix devices. | ||
| deviceTypeCode | Yes | string | CSRSDWAN | CSRSDWAN, PRISMA-SDWAN | 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. | |
| 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. | |
| licenseMode | Yes | string | BYOL | License type. For now, the only available option is BYOL (bring your own license). | |
| licenseToken | Conditional | string | 4567890 | License token. You can enter either a token or a license FileId for Fortinet SD-WAN devices. | |
| licenseFileId | Conditional | string | 6651aef5-e738-411f-8675-5f6b7b9cd429 | License file Id. Mandatory for Cisco SD-WAN devices. | |
| day0TextFileId | Conditional | string | 4cfb5675-5c3f-4275-adba-0c9e3c26c96b | Some devices require a day0TextFileId. Upload your license file by calling Upload File. You'll get a fileUuid in the response. You can enter the value in the day0TextFileId field of the create payload to create a virtual device. Check the payloads of individual devices (provided as Postman Scripts) for details. | |
| metroCode | Yes | string | SV | Metro code. You may provide two different metros for your 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. | |
| 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 secondary device if you have a redundant device. | |
| packageCode | Yes | string | ESSENTIALS | Software package code. | |
| version | Yes | string | 16.12.1e | Version. | |
| termLength | Yes | integer | 24 | 1, 12, 24, 36 | Billing term length in months. Default = 1 month. |
| throughput | integer | 500 | Throughput. Mandatory for Cisco SD-WAN. You cannot specify throughput for CloudGenix devices. | ||
| throughputUnit | string | Mbps | Throughput unit. Mandatory for Cisco SD-WAN. 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. | |
| 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 ACL. | |
| accountNumber | Conditional | 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 | Conditional | 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. | ||
| projectId | Conditional | string | XXXXXX | Customer project Id. Required for CRH-enabled customers. | |
| purchaseOrderNumber | No | string | 3456789 | Purchase order number. Purchase order information will be included in your order confirmation email. | |
| orderReference | No | string | 645678A | Enter a short name/number to identify this order on the invoice. | |
| core | Yes | integer | 4 | The number of cores you want for your device. | |
| interfaceCount | No | integer | 24 | Interface count. To find out the allowed number of interfaces for your selected core, call Get Allowed Interfaces. | |
| deviceManagementType | Yes | string | SELF-CONFIGURED | SD-WAN devices are self-configured. | |
| hostNamePrefix | No | string | myHost | Host name for identification. 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 digit. The length should be between 2-30 characters. Exceptions - FTDv 2-14; Aruba 2-24. | |
| ipType | Conditional | string | DHCP | DHCP or STATIC | This feature is only available for CSRSDWANs. You may specify the ipType as DHCP or STATIC. If the ipType is DHCP, then Equinix will assign /29 IP address to the WAN/SSH interface. This field will default to STATIC if you do not provide an ipType. |
| sshInterfaceId | No | string | 5 | You may choose any available interface on the device. To find out the available interfaces, call Get Allowed Interfaces. | |
| channelPartner | No | string | SDCI | The name of the channel partner. | |
| secondary | object | secondary{} | An object containing the optional secondary device details to create a redundant device. |
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 redundant device.
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 SD-WAN virtual device. |
| secondaryUuid | string | 92c2e49d-2c35-432d-a9af-016920bef70c | Unique identifier of the secondary SD-WAN virtual device (HA). |
If you get “Access Denied,” contact your local Equinix Service Desk for Portal access.
When an SD-WAN 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 | 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 if you have requested a redundant device. |
| WAITING_FOR_SECONDARY | The primary device is ready but the secondary is not. This state may appear if you have requested a redundant device. |
| FAILED | The device creation failed. |
| PROVISIONED | The device is ready. |
| DEPROVISIONING | Equinix accepted the customer's request to delete the virtual device. |
| DEPROVISIONED | The device is de-provisioned/deleted. |
When an end-user deletes a device using the Delete Virtual Devices API, the device transitions through the following states within the Equinix infrastructure.
| status | Description |
|---|---|
| DEPROVISIONING | Equinix accepted the customer's request to delete the virtual device. |
| DEPROVISIONED | The device is de-provisioned/deleted. |