Launch Self-Configured Device
A customer has 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. Here are the steps to create a Self-Configured device using APIs:
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) 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) If you want to launch a Cisco FTD Firewall, you must provide the vendorConfig object. If you choose the "FMC" managementType, you must also provide the controller IP address and the activation key.
5) 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) Include either an existing ACL template or create a new ACL template by calling the Create ACL Template method. Pass the unique Id of the new/existing template in the payload when creating your 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 device. Otherwise, follow the steps:
To save a device draft, you must provide deviceTypeCode, accountNumber/accountReferenceId, and metroCode.
See Creating a Self-Configured Edge Device to understand the business details. Sample payloads for all device types can be found in the Postman collection in Step 4.
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 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).
To find out the allowed number of interfaces for your selected core, call Get Allowed Interfaces. 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 the Bring Your Own Licensing (BYOL) option for devices. You may upload a license file or a license code/token/ID, depending on what your vendor offers.
We don't support uploading a license for Arista device. However, you can log in to your device after it is created to upload a license to increase your throughput.
Cisco and Palo Alto provide license tokens. Enter the license token in the licenseToken field.
Juniper provides license files. To bring your own license (BYOL) for a Juniper device, use the Post License File 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.
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 device, you must 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 device.
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 |
Download Postman Scripts for exact payloads to create devices. Every device has its own payload, depending on the vendor of the device.
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.
3) In the case of Cisco FTD devices, the management type for both the primary and the secondary devices must be the same.
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 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",
"agreeOrderTerms": true,
"termLength": "1",
"licenseMode": "BYOL",
"packageCode": "STD",
"virtualDeviceName": "Test-device-001-SROY",
"notifications": [
"test@equinix.com"
],
"hostNamePrefix": "TC12",
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"accountNumber": "200541",
"version": "18.4R2-S1.4",
"interfaceCount": 10,
"deviceManagementType": "SELF-CONFIGURED",
"core": 5,
"userPublicKey": {
"username": "userName",
"keyName": "keyName"
},
"additionalBandwidth": "100"
}
'
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 '
{
"metroCode": "DC",
"deviceTypeCode": "C8000V",
"agreeOrderTerms": true,
"termLength": "1",
"licenseMode": "BYOL",
"packageCode": "network-advantage",
"virtualDeviceName": "Test-device-002-SROY",
"notifications": [
"test@equinix.com"
],
"hostNamePrefix": "TC01",
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"accountNumber": "201148",
"version": "17.06.01a",
"interfaceCount": 10,
"deviceManagementType": "SELF-CONFIGURED",
"core": 2,
"userPublicKey": {
"username": "sroy",
"keyName": "keyWIQzB"
},
"sshInterfaceId": "3",
"channelPartner": "SDCI",
"secondary": {
"metroCode": "DC",
"hostNamePrefix": "TC02",
"notifications": [
"test@equinix.com"
],
"virtualDeviceName": "Test-device-001-SROY - secondary",
"additionalBandwidth": "100",
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"accountNumber": "201148",
"sshInterfaceId": "4"
},
"additionalBandwidth": "100"
}
'
A sample curl request to create a Cisco FTD secondary device with no internet access.
curl -X
POST "https://api.equinix.com/ne/v1/devices?draft=false"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '
{
"deviceTypeCode": "Cisco_NGFW",
"licenseMode": "BYOL",
"packageCode": "FTDv5",
"virtualDeviceName": "NEAut-",
"metroCode": "#(supportedMetro)",
"notifications": [
"t@t.com"
],
"hostNamePrefix": "test",
"interfaceCount": 10,
"deviceManagementType": "SELF-CONFIGURED",
"core": 4,
"version": "7.0.4-55",
"vendorConfig": {
"managementType": "FDM"
},
"connectivity": "PRIVATE",
"secondary": {
"hostNamePrefix": "test-123",
"metroCode": "#(supportedMetroForSec)",
"notifications": [
"t@t.com"
],
"virtualDeviceName": "test-secondary",
"vendorConfig": {
"managementType": "FDM"
}
}
}
'
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 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). |
Body parameters:
Body Parameter Name | Mandatory | Type | Example | Possible Values | Description |
---|---|---|---|---|---|
deviceTypeCode | Yes | string | C8000V | 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 | Conditional | string | XXXXXXX | 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 | XXXXXXX | 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. | |
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. | |
hostNamePrefix | Yes | string | mySR | 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. | |
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. | |
licenseCategory | No | string | flex | flex, classic | This field is not necessary and will be deprecated in the future. |
licenseToken | Conditional | string | 4567890 | License token. Some devices require a token. Check the payloads of individual devices (provided as Postman Scripts) for details. | |
licenseFileId | Conditional | string | 4cfb5675-5c3f-4275-adba-0c9e3c26c96b | Some devices require a licenseFileId. You must first upload the license file using the Post License method to get a licenseFileId. Check the payloads of individual devices (provided as Postman Scripts) for details. | |
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 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. | |
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. |
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. NGINX supports only MGMT interface ACL. | |
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. | |
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 | Interface count. To find out the allowed number of interfaces for your selected core, call Get Allowed Interfaces. | |
userPublicKey | Yes | object | "userPublicKey": { "username": "sroy", "keyName": "keyName" } | An object containing the username and keyName. | |
userPublicKey.username | Yes | string | sroy | Username. | |
userPublicKey.keyName | No | string | keyName | This field is not mandatory. If you choose to provide a keyName, make sure it is an existing keyName associated with an existing keyValue. To set up a new keyName and keyValue pair, call Create Public Key. | |
sshIntefaceId | No | string | 3 | You may specify any available device interface as the sshInterfaceId. To find out the available interfaces, call Get Allowed Interfaces. | |
smartLicenseUrl | No | string | https://www.equinix.com | License URL. This field is only relevant for Cisco ASAv devices. | |
vendorConfig | Conditional | object | An object that has vendor-specific parameters. This is not required for most devices. | ||
vendorConfig.managementType | Conditional | string | FMC | This is required for Cisco FTD Firewall devices. If you choose "FMC," you must also provide the controller IP and the activationKey. | |
vendorConfig.controller1 | Conditional | string | 1.1.1.1 | The IP address of the controller. This field is relevant if you have chosen the "FMC" management type (Cisco FTD devices). | |
vendorConfig.activationKey | Conditional | string | 454454 | The activation key. This field is relevant if you have chosen the "FMC" management type (Cisco FTD devices). | |
vendorConfig.userName | Conditional | string | sr1user12 | This field is relevant for Prosimo devices. | |
vendorConfig.connectToCloudVision | Conditional | boolean | true | Only relevant for Arista devices. A "true" value connects your Arista device to Cloud Vision. | |
vendorConfig.cvpType | Conditional | string | As-a-Service | Only relevant for Arista devices. Possible values: As-a-Service or On-Premise. | |
vendorConfig.cvpFqdn | Conditional | string | www.NetworkSolutions.com | Fully qualified domain name for Cloud Vision As-a-Service. Only relevant for Arista devices. CvpFqdn is required if connectToCloudVision=true and cvpType=As-a-Service. | |
vendorConfig.cvpIpAddress | Conditional | string | 192.168.0.10 | Only relevant for Arista devices. CvpIpAddress is required if connectToCloudVision=true and cvpType=On-Premise. | |
vendorConfig.cvaasPort | Conditional | string | 443 | Only relevant for Arista devices. CvaasPort is required if connectToCloudVision=true and cvpType=As-a-Service. | |
vendorConfig.cvpPort | Conditional | string | 443 | Only relevant for Arista devices. CvpPort is required if connectToCloudVision=true and cvpType=On-Premise. | |
vendorConfig.cvpToken | Conditional | string | 123 | Only relevant for Arista devices. CvpToken is required if connectToCloudVision=true and (cvpType=On-Premise or cvpType=As-a-Service). | |
vendorConfig.provisioningKey | Conditional | string | sampleKey | Relevant for Zscaler devices. | |
vendorConfig.privateAddress | No | string | 192.168.20.32 | Private address. Relevant for BlueCat devices. | |
vendorConfig.privateCidrMask | No | string | 24 | Private CIDR Mask. Relevant for BlueCat devices. | |
vendorConfig.privateGateway | No | string | 192.168.20.1 | Private gateway. Relevant for BlueCat devices. | |
vendorConfig.licenseId | No | string | 000000123457777 | License Id. Relevant for BlueCat devices. | |
vendorConfig.panoramaIpAddress | No | string | 1.1.1.1 | IP address of the Panorama controller. Provide this value to have Panorama integration. Relevant for Palo Alto Self-Configured devices with Internet Access | |
vendorConfig.panoramaAuthKey | No | string | 123456 | This key supports secure onboarding of the Palo Alto firewall devices. Provide this value to have Panorama integration. Relevant for Palo Alto Self-Configured devices with Internet Access. | |
vendorConfig.licenseId | No | string | 000000123457777 | License Id. Relevant for BlueCat devices. | |
channelPartner | No | string | SDCI | The name of the channel partner. | |
cloudInitFileId | Conditional | string | 2d732d49-7a00-4839-aeca-8a2ff89da691 | A required parameter to create an Aviatrix device. Upload your bootstrap config file generated from the Aviatrix Conroller portal using the Upload File API. You will get a unique Id in response that you can submit as cloudInitFileId to create an Aviatrix device. | |
ipType | Conditional | string | DHCP | DHCP or STATIC | 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. Arista only supports DHCP. |
connectivity | No | string | INTERNET-ACCESS | INTERNET-ACCESS, PRIVATE, INTERNET-ACCESS-WITH-PRVT-MGMT | Specifies the type of connectivity on the device. Default is INTERNET-ACCESS. A PRIVATE device will not have ACLs or bandwidth. |
secondary | No | object | secondary{} | The 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 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/devices/{uuid} | Description |
---|---|
DEPROVISIONING | Equinix accepted the customer's request to delete a virtual device. |
DEPROVISIONED | The device is de-provisioned/deleted. |