Skip to main content
Index

Launch Cluster Device

 

Create a cluster

 

To create a cluster you must do the following:

 

1) Have the device type (deviceTypeCode), the number of cores (core), the software type (packageCode and version), and 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) Know the license option (licenseMode) you want. As of now, we only offer the BYOL (bring your own license) option. You may need to upload a token or a license file, depending on your vendor's requirements. See Step 3 for more details. 

 

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) To have access control, you may either use 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. 

If you have all the necessary information, skip ahead to Step 4and create a cluster. Otherwise, follow the steps:

 

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

 

Refer to Creating a Juniper vSRX Cluster for more details. 

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 the Getting Started section for instructions on how to create a client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call the 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 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. You may choose to have the default or the maximum interface count for your device. 

 

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 must upload two different license files before you can 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
 Body Parameters

 additionalBandwidth, deviceTypeCode, diverseFromDeviceUuid, hostNamePrefix, metroCode,

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

 virtualDeviceName, orderingContact, aclTemplateUuid, accountNumber, accountReferenceId, 

 purchaseOrderNumber, interfaceCount, deviceManagementType, core, userPublicKey { username, keyName}, clusterDetails {clusterName, clusterNodeDetails{ node0: {vendorConfig{hostName, activationKey, controllerFqdn, rootPassword}, licenseFileId, licenseToken}, node1: {vendorConfig{hostName, rootPassword}, licenseFileId, licenseToken}}

 

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",
    "aclTemplateUuid": "41e351dd-5111-4ca6-8b9f-d29924f6885a",
    "accountNumber": "201148",
    "version": "18.4R3-S2",
    "interfaceCount": 8,
    "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-2TDJ",
                "controllerFqdn": "demo.velocloud.net",
                "rootPassword": "myPassw0rd!"
            },
            "node1": {
                "rootPassword": "myPassw0rd#"
            }
        }
    },
    "licenseMode": "BYOL",
    "packageCode": "VeloCloud-4",
    "virtualDeviceName": "velo-cluster",
    "notifications": [
        "test@equinix.com"
    ],
    "aclTemplateUuid": "fd788e6e-de01-46de-9360-19fa591aa21d",
    "accountNumber": "2393479",
    "version": "3.4.2",
    "interfaceCount": 8,
    "deviceManagementType": "SELF-CONFIGURED",
    "core": 4,
    "userPublicKey": {
        "username": "sroy",
        "keyName": "key7YFfL"
    },
    "additionalBandwidth": "200"
}

'

 

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 No 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 No 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. 
hostName Yes string mySR   Hostname. This gets included as part of an FQDN that ensures the device is reachable from approved sources if desired. Only a-z, A-Z, 0-9, and hyphen(-) are allowed. It should start with a letter and end with a letter or a digit. Also, it should be a minimum of 2 and a maximum of 10 characters long. 
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.
aclTemplateUuid No string 39289456-a63e-47d4-927c-5161cfb77500   The template Id of a device ACL template created using the POST ACL Template method. 
purchaseOrderNumber No string 3456789   Purchase order number. Optional field that customers can use to track this device creation to their own purchase order number. 
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   Whether you want the default number or the maximum number of interfaces available on the device.
userPublicKey Yes object

 "userPublicKey": {

        "username": "sroy",

        "keyName": "keyName"

    }

  An object containing the username and keyName. 
userPublicKey.username Yes string sroy   Username.
userPublicKey.keyName Yes string keyName   Key name. 
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-2TDJ   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 myPassw0rd!   The CLI password of the device. This field is relevant only for the Velocloud SDWAN cluster.
vendorConfig.hostname No string PANW-Cluster-T1-Node0   Hostname. This is necessary for Palo Alto, Juniper, and Fortinet clusters. 
node0.licenseFileId No string ebfc3126-496b-4976-9bbb-f77c9b296207   License file Id. This is required for Fortinet and Juniper clusters.
node0.licenseToken No 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   Hostname. 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.
node1.licenseFileId No string ebfc3126-496b-4976-9bbb-f77c9b296208   License file Id. This is necessary for Fortinet and Juniper clusters. 
node1.licenseToken No string I3372904   License token. This is necessary for Palo Alto clusters. 

 

 

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.

 

Cluster Status Diagram

 

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. 

Sample Payloads

Parameter Name Juniper Palo Alto Fortinet Velocloud SDWAN
deviceTypeCode VSRX PA-VM FG-VM VELOCLOUD-SDWAN
hostname myHost123 myHost123 myHost123  
licenseMode BYOL BYOL BYOL BYOL
licenseFileId     5dc4f08a-8b3c-4c02-8b72-0aa943539006  
licenseToken   4545454    
notifications test@equinix.com test@equinix.com test@equinix.com test@equinix.com
metroCode DC SY SY SY
aclTemplateUuid c72df2e3-a911-4109-bf9e-0376003c5a9a c72df2e3-a911-4109-bf9e-0376003c5a9a c72df2e3-a911-4109-bf9e-0376003c5a9a c72df2e3-a911-4109-bf9e-0376003c5a9a
packageCode STD VM300 VM04 VeloCloud-4
version

18.4R3-S2

9.0.4 6.4.0 3.4.2
virtualDeviceName sroyClusterDevice sroyClusterDevice sroyClusterDevice velo-cluster
orderingContact subuser01 subuser01 subuser01 subuser01
accountNumber 1234567 1234567 1234567 1234567
addtionalBandwidth 100 100 100 100
purchaseOrderNumber 888888 888888 888888  
deviceManagementType SELF-CONFIGURED SELF-CONFIGURED SELF-CONFIGURED SELF-CONFIGURED
core 5 8 4 4
interfaceCount 8 10 10 8
userPublicKey.username test test test test
userPublicKey.keyName keyName keyName keyName keyName
clusterName myCluster myCluster myCluster myCluster
node0.vendorConfig.hostName SR123 SR123 SR123 SR123
node0.licenseFileId 5dc4f08a-8b3c-4c02-8b72-0aa943539006   5dc4f08a-8b3c-4c02-8b72-0aa943539006  
node0.licenseToken   4545454    
node0.activationKey       GJUK-JM2X-59BJ-2TDJ
node0.controllerFqdn       demo.velocloud.net
node0.rootPassword       myPassw0rd!
node1.vendorConfig.hostName SR012 SR012 SR012 SR012
node1.licenseFileId 5dc4f08a-8b3c-4c02-8b72-0aa943539007   5dc4f08a-8b3c-4c02-8b72-0aa943539007  
node1.licenseToken   4545455    
node1.rootPassword       myPassw1rd!