Skip to main content

Launch Cluster Device

Prerequisites

  1. Authenticate - Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication. Refer to API Authentication for instructions on how to call the OAuth API to validate and authenticate your credentials.

  2. Call Get Device Types to find out which cluster device (e.g., router or firewall) you want to launch on the NE platform. You will learn about the metro regions where virtual device are available, vendors of devices, the available number of cores, and the software packages and their versions. Select deviceTypeCode, metroCode, core, packageCode, and version.

  3. Call Get Allowed Interfaces to find out the allowed number of interfaces for your selected core. You may select any available device interface as sshInterfaceId. Otherwise, Equinix will choose the first available interface.

  4. 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. Create an account if you do not have one.

    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.

Licensing Options

As of now, we only offer the BYOL (bring your own licensing) option for clusters.

  • Juniper Cluster - It is not necessary to upload license files for a Juniper Cluster. However, you may upload two license files. To upload two license files, call Post License File twice. You will get license file IDs in the response that you can use to create a cluster.

  • Palo Alto Cluster - You must upload two license tokens from the vendor. The license tokens can be the same or different.

  • Fortinet Cluster - You don't need to enter a token or license. If you want to upload license files, you must upload two different license files. To upload two license files, call Post License File twice. You will get license file IDs in the response that you can use to create a cluster.

  • Velocloud SD-WAN Cluster You do not need to upload a license file or token. 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.

Create Cluster Device

POST /ne/v1/devices
MethodPOST
URL or End Point/ne/v1/devices
HeadersAuthorization token, Content-Type
Query Parametersdraft, draftUuid

Note: By creating a virtual device, you accept the Order Terms. Call Get Order Terms to review the details.

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

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

For a complete list of parameters and options, see the API Reference.

Sample Response

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

Device Status

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 statesDescription
INITIALIZINGEquinix is in the process of reserving resources and creating the device.
PENDING_ACCOUNTCustomer's account is not approved. The device creation will continue once the account gets approved.
PROVISIONINGThe device is booting.
PENDING_ORDERThis 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_SIGNATUREThe customer has not yet accepted Network Edge terms.
CANCEL_ORDERThe order from Siebel to NE is canceled. This status only applies to orders coming to Network Edge from Siebel.
WAITING_FOR_PRIMARYThe secondary device is ready but the primary is not. This state may appear if you have requested a redundant device.
WAITING_FOR_SECONDARYThe primary device is ready but the secondary is not. This state may appear if you have requested a redundant device.
FAILEDThe device creation failed.
PROVISIONEDThe device is ready.
DEPROVISIONINGEquinix accepted the customer's request to delete the virtual device.
DEPROVISIONEDThe 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.

statusDescription
DEPROVISIONINGEquinix accepted the customer's request to delete the virtual device.
DEPROVISIONEDThe device is de-provisioned/deleted.