Launch Cluster Device
Here are the steps to create a cluster using APIs:
1) Find out the following information:
- the device test 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 cluster device (metroCode)
2) Have your Equinix account number ready. Your account must be in the Active or Pending status.
3) License option (licenseMode). As of now, we only offer the BYOL (bring your own license) option for most cluster devices. You may need to upload a token or a license file, depending on your vendor's requirements. See Step 3 for more details.
Note: Sub-customers cannot choose the subscription licensing option. Even resellers creating devices for sub-customers can only choose the BYOL option.
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) Include an existing ACL template or create a new ACL template by calling the Create ACL Template method. Copy the unique Id of the new/existing ACL template and use it in the payload to create 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 cluster. Otherwise, follow the steps:
To save a device draft, you must provide a deviceTypeCode, an accountNumber/accountReferenceId, and a metroCode.
See Creating a Juniper vSRX Cluster for more details.
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 to find out which cluster 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 options. 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 account
Call Get Accounts {metro} 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 method to create a device for your customer.
Step 3: Licensing Options
As of now, we only offer the BYOL (bring your own licensing) option.
a) To create a Juniper cluster, you may upload two license files before you create a cluster. To upload a license file, call Post License File. You will get a license file ID in the response that you can use to create a cluster.
b) To create a Palo Alto cluster, you must upload two license tokens from the vendor. The license tokens can be the same or different.
c) To create a Fortinet cluster, you don't need to enter a token or a license. If you want to upload license files, you must upload two different license files to create a cluster. To upload a license file, call Post License File. You will get a license file ID in the response that you can use to create a cluster.
d) You do not need to upload a license file or token to create a Velocloud SDWAN cluster. However, you must provide your activation key. If your license fails to register after your device is created, you must log in to the device and upload the license. Then, call Update Virtual Device with the status value "PROVISIONED."
Step 4: Create Cluster 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.
A sample curl request to create a vSRX cluster:
curl -X
POST "https://api.equinix.com/ne/v1/devices?draft=false"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '
{
"deviceTypeCode": "VSRX",
"clusterDetails": {
"clusterName": "sroy-juniper",
"clusterNodeDetails": {
"node0": {
"vendorConfig": {
"hostname": "sr012"
},
"licenseFileId": "1274fe9f-511c-436f-bc0c-14c876ec55da"
},
"node1": {
"vendorConfig": {
"hostname": "sr123"
},
"licenseFileId": "65a9be3f-57fb-4c4d-a15b-40950951bc13"
}
}
},
"metroCode": "SV",
"termLength": "1",
"licenseMode": "BYOL",
"packageCode": "STD",
"virtualDeviceName": "Test-device-001-SROY",
"notifications": [
"test@equinix.com"
],
"hostname": "sr012",
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"accountNumber": "201148",
"version": "18.4R3-S2",
"interfaceCount": 8,
"agreeOrderTerms": true,
"deviceManagementType": "SELF-CONFIGURED",
"core": 5,
"userPublicKey": {
"username": "sroy",
"keyName": "keyLlhzL"
},
"additionalBandwidth": "100"
}
'
A sample curl request to create a Velocloud SDWAN cluster:
curl -X
POST "https://api.equinix.com/ne/v1/devices?draft=false"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '
{
"metroCode": "SY",
"deviceTypeCode": "VELOCLOUD-SDWAN",
"termLength": "1",
"clusterDetails": {
"clusterName": "sroy-velo-cluster",
"vendorConfig": {
"node0": {
"activationKey": "GJUK-JM2X-59BJ-SAMPLE",
"controllerFqdn": "demo.velocloud.net",
"rootPassword": "TestPassword!"
},
"node1": {
"rootPassword": "TestPassword#"
}
}
},
"licenseMode": "BYOL",
"packageCode": "VeloCloud-4",
"virtualDeviceName": "velo-cluster",
"notifications": [
"test@equinix.com"
],
"aclDetails": [
{
"uuid": "fb2e69bb-cbd7-40c4-bc01-8bcc5fa741c2",
"interfaceType": "WAN"
}
],
"accountNumber": "2393479",
"version": "3.4.2",
"interfaceCount": 8,
"deviceManagementType": "SELF-CONFIGURED",
"agreeOrderTerms": true,
"core": 4,
"userPublicKey": {
"username": "sroy",
"keyName": "key7YFfL"
},
"additionalBandwidth": "200"
}
'
A sample curl request to create a PANW cluster 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": "PA-VM",
"clusterDetails": {
"clusterName": "NEAut-",
"clusterNodeDetails": {
"node0": {
"vendorConfig": {
"hostname": "PANCluster"
}
},
"node1": {
"vendorConfig": {
"hostname": "PANCluster"
}
}
}
},
"metroCode": "#(supportedMetro)",
"zoneCode": "Zone1",
"termLength": "1",
"licenseMode": "BYOL",
"packageCode": "VM100",
"virtualDeviceName": "NEAut-",
"notifications": [
"t@t.com"
],
"version": "10.1.3",
"interfaceCount": 10,
"deviceManagementType": "SELF-CONFIGURED",
"core": 2,
"connectivity": "PRIVATE"
}
'
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 | VSRX | 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 | 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. | |
| sshIntefaceId | No | string | 3 | You may specify any available device interface as the sshInterfaceId. To find out the available interfaces, call Get Allowed Interfaces. | |
| accountReferenceId | Conditional | 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. | |
| projectId | Conditional | string | XXXXXX | Customer project Id. Required for CRH-enabled customers. | |
| hostname | No | 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 characters; Aruba 2-24 characters. | |
| 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. | |
| 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 cluster devices. |
| metroCode | Yes | string | SV | Metro code. | |
| 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. | |
| packageCode | Yes | string | STD | Software package code. | |
| version | Yes | string | 14.4R3-S2 | 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 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. | |
| deviceManagementType | Yes | string | SELF-CONFIGURED | Cluster devices are self-configured. | |
| 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. | |
| channelPartner | No | string | SDCI | The name of the channel partner. | |
| clusterDetails | Yes | object | An object that has the cluster details. | ||
| clusterName | Yes | string | clusterSROY123 | The name of the cluster. | |
| clusterNodeDetails | Yes | object | An object that has the cluster details. | ||
| node0 | Yes | object | An object that has node0 details. | ||
| node0.vendorConfig | Yes | object | An object that has vendorConfig details of node0. | ||
| vendorConfig. activationKey | No | string | GJUK-JM2X-59BJ-INVALID | Activation key. This is required for Velocloud clusters. | |
| vendorConfig.controllerFqdn | No | string | demo.velocloud.net | Controller fqdn. This is required for Velocloud clusters. | |
| vendorConfig.rootPassword | No | string | TestPassword! | The CLI password of the device. This field is relevant only for the Velocloud SDWAN cluster. | |
| vendorConfig.adminPassword | No | string | TestPassword! | Password. This field is relevant for the Fortinet SDWAN cluster device. | |
| vendorConfig.controller1 | No | string | 1.1.1.1 | System IP Address. Mandatory for the Fortinet SDWAN cluster device. | |
| vendorConfig.hostname | No | string | PANW-Cluster-T1-Node0 | 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. This is necessary for Palo Alto, Juniper, and Fortinet clusters. | |
| 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. | |
| node0.licenseFileId | Conditional | string | ebfc3126-496b-4976-9bbb-f77c9b296207 | License file Id. This is required for Juniper clusters. | |
| node0.licenseToken | Conditional | string | I3372903 | License token. This is necessary for Palo Alto clusters. | |
| node1 | Yes | object | An object that has node1 details. | ||
| node1.vendorConfig | Yes | object | An object that has vendor config details of node1. | ||
| vendorConfig.hostname | No | string | PANW-Cluster-T1-Node1 | 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. This is necessary for Palo Alto, Juniper, and Fortinet clusters. | |
| vendorConfig.rootPassword | No | string | Welcome@1 | The CLI password of the secondary device. This field is relevant only for the Velocloud SDWAN cluster. | |
| vendorConfig.adminPassword | No | string | 3455454 | Password. This field is relevant for the Fortinet SDWAN cluster device. | |
| 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. | |
| node1.licenseFileId | Conditional | string | ebfc3126-496b-4976-9bbb-f77c9b296208 | License file Id. This is necessary for Juniper clusters. | |
| node1.licenseToken | Conditional | string | I3372904 | License token. This is necessary for Palo Alto clusters. | |
| 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. |
Note: "aclTemplateUuid" field is deprecated. Please use "aclDetails" instead.
Sample response:
202: Request accepted.
{
"uuid": "34b7838c-ec82-4166-ac19-efa03b4e34fe",
"deviceIds": {
"node0": "34b7838c-ec82-4166-ac19-efa03b4e34fe",
"node1": "f27f1475-3c7f-447f-b0db-e3bb3af3de16"
},
"clusterId": "27eea9aa-327b-431b-bf62-3cee4d880f2e"
}
The description of the response payload is as follows:
| Field | Type | Example Values | Description |
|---|---|---|---|
| uuid | string | b43ba509-a7d9-4334-8dee-dc4f29bf2e77 | The unique Id of the node0 cluster device. |
| node0 | string | b43ba509-a7d9-4334-8dee-dc4f29bf2e77 | The unique Id of the node0 cluster device. |
| node1 | string | f27f1475-3c7f-447f-b0db-e3bb3af3de16 | The unique Id of the node1 cluster device. |
| clusterId | string | 27eea9aa-327b-431b-bf62-3cee4d880f2e | The unique Id of the cluster device. |
When a cluster is created, the self-configured cluster transitions through various states within the Equinix infrastructure. These states can be monitored using the "status" response attribute of the Get Virtual Device {uuid} method. Your cluster must be provisioned and your license must be registered before you can use this cluster to connect to cloud service providers.
| Virtual device "status" | Description |
|---|---|
| INITIALIZING | Equinix is in the process of reserving resources and creating the cluster device. |
| PROVISIONING | The device is booting. |
| WAITING_FOR_REPLICA_CLUSTER_NODES | Other nodes are going through the provisioning process. |
| CLUSTER_SETUP_IN_PROGRESS | The cluster setup is in progress. |
| FAILED | The cluster creation failed. |
| LICENSE_FAILED | If your license fails to register, you must log in to the device and upload the license. Then, you must call Update Virtual Device with the status value "PROVISIONED." |
| PROVISIONED | The cluster is provisioned. |
When end-users delete a cluster using the Delete Virtual Devices method, the cluster 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. |