Contents


Configure SoftLayer components for use with Account Defined Network

Provision SoftLayer infrastructure components for ADN using SoftLayer RESTful APIs

Comments

SoftLayer's new Account Defined Network (ADN) feature enables total control of hosted servers in private networks. With it, you can provision new Bare Metal and virtual servers into IP address ranges of your choosing. You can then use IP numbering to organize the servers into logical groups for clustering, task distribution, disaster recovery, service localization, and more.

Before you can use ADN, however, you must provision and configure certain required infrastructure components. In this tutorial, you will learn how to provision the required SoftLayer infrastructure components for ADN using SoftLayer RESTful APIs. Using SoftLayer, portal users can view the details about the required components along with their pricing specifics. SoftLayer APIs can perform most of the functions of the SoftLayer portal. Using SoftLayer APIs, you can provision as well as perform management operations on the infrastructure components. This allows you to automate repeatable tasks.

Infrastructure setup and configuration is a time-consuming process.... SoftLayer provides a uniform and standard API library that can be accessed via various methods and tools, and is transparent to the SoftLayer portal.

RESTful APIs have various advantages over other methods of API access. For example, they are not programming language–dependent, they are easy to understand, they require minimal coding skills, and they can be conveniently executed from any Linux terminal using the CURL utility.

To begin our discussion, here are some of the key terms we'll be using in this tutorial:

Key terms

  • API user and API key

API user is specifically created in the SoftLayer customer portal account to call APIs. This user has an associated API key, which is an authentication token that's reserved for making API calls.

  • REST API URL

REST API uses URLs to make API calls over HTTPS. URLs represent the SoftLayer Object hierarchy, which is easy to understand.

Here's the format of the URL:

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]

And here's an example URL for placing an order:

https://[userid]:[apikey]@api.softlayer.com/rest/v3/SoftLayer_Product_Order/placeOrder
  • JSON object

JSON (JavaScript Object Notation) is a simple human-readable object notation that's structured for storing key-value pairs. The SoftLayer API accepts and returns the API call details in JSON-formatted text. The data required to place the order—such as type of service, quantity, and related properties—are put into JSON format and saved in a text file. This file is then used by the CURL utility to make an API call.

  • CURL

CURL is a command-line utility that's used to make API calls by sending HTTPS requests to SoftLayer.

Here's an example of how it's used:

curl -H "Content-Type:application/json" --data @Order-data.json https://<userid>:<apikey>@api.softlayer.com/rest/v3/SoftLayer_Product_Order/placeOrder

In the example above, @Order-data.json specifies a text file that contains order details in JSON format.

How a REST call works

The diagram in Figure 1 illustrates the flow of a REST call.

Figure 1. Diagram showing REST call flow
Diagram showing REST call flow
Diagram showing REST call flow
  • A REST call is made to the SoftLayer API service from the terminal using the CURL utility. The JSON data required for this call is loaded from a text file.
  • The SoftLayer API service reads the request along with the JSON data, checks its correctness, and performs the required action in the SoftLayer infrastructure.
  • The order details are returned if the action is successful; otherwise, an error message is returned.
  • The result of the action is returned to the terminal from which the REST call was made.

Use shell scripts to automate the execution of CURL commands

Shell scripts contain CURL commands that automate the instantiation of REST calls. Figure 2 illustrates how the scripts are executed.

Figure 2. Diagram showing execution of scripts
Diagram showing execution of scripts
Diagram showing execution of scripts
  1. The SLObject.sh script (the actual script name is different) containing a CURL command is executed in a terminal.
  2. The Order-Data.Json file contains the order data in JSON format, and its name is passed to the CURL command.
  3. After execution is complete, the script creates the output file SLObject.Output, which contains the return data from the SoftLayer API.

Location of the shell scripts and JSON files

The shell scripts and the required JSON data files shown in this tutorial are available at the following GitHub repository:

https://github.com/yash-nigam/ADN-REPO

These scripts can be used in the following order.

  1. Create network.
  2. Create subnet.
  3. Create virtual guest (vm – web).
  4. Create virtual guest (vm – App).
  5. Create Bare Metal (install database).
  6. Create Evault storage for virtual guest.
  7. Create Evault Bare Metal.
  8. Create object storage account.
  9. Order block storage.
  10. Authorize block storage to a virtual guest or Bare Metal.
  11. Order NetScaler VPX.

For the convenience of the user, the files have been organized into the following hierarchy:

  • /ADN/src/Script: This folder contains all the shell script files.
  • /ADN/src/Json: This folder contains all the JSON data files.
  • /ADN/src/Output: This folder will contain the output of the execution of a shell script.

Download the ADN folder from the Git repository mentioned above and execute the shell scripts on a local machine.

Prerequisites

Before you execute the scripts, be sure to check and install CURL:

  • Log in with root user on the system and run the following command.

    curl –V
  • The following output should appear if CURL is installed:

    curl 7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.19.1 Basic ECC zlib/1.2.3 libidn/1.18 libssh2/1.4.2
  • If CURL is not installed, install it using the following command:

    yum install curl

Services and methods used in REST calls

Each SoftLayer object is related to a specific service. Various methods are associated with a service which, when called, perform a specific operation on the object of that service. Each object in SoftLayer is identified by a unique ID that needs to be included in the REST call. This table lists the services and methods associated with each REST call:

SoftLayer objectService usedMethod used
Create network SoftLayer_Network createObject
Create subnet SoftLayer_Network/
<NetworkID>
createSubnet/createObject
Create a virtual guest SoftLayer_Virtual_Guest createObject
Create Bare Metal server SoftLayer_Product_Order placeOrder
Create Evault storage SoftLayer_Product_Order placeOrder
Create object storage account SoftLayer_Product_Order placeOrder
Create block storage SoftLayer_Product_Order placeOrder
Authorize block storage SoftLayer_Network_Storage
_Iscsi/<BlockStorageID/
allowAccessFromVirtualGuest
Order NetScaler SoftLayer_Product_Order placeOrder

Package and price IDs

Along with Service, Object ID, and Method details, certain other details also need to be passed with the REST call to provision an object. Package and price IDs are used for billing purposes, and are required for all REST calls where the placeOrder method is used.

How to find package and price IDs

Use the following REST call to find package IDs:

curl https://<userid>:<apikey>@api.softlayer.com/rest/v3/SoftLayer_Product_Package/getAllObjects

Find price IDs for a specific package ID by using this REST call:

curl https://<userid>:<apikey>@api.softlayer.com/rest/v3/SoftLayer_Product_Package/222/getItemPrices

You can also display the package and price IDs from the SoftLayer portal using the Firebug extension in the Firefox browser:

  1. On the SoftLayer product page, go to Order devices and select a device to order.
  2. Enable the Firebug extension in the Order window.
  3. In the Firebug window, go to the NET tab. Select the Persist and All buttons.
  4. In the Order window, proceed to the Add to Order page.
  5. A POST entry will appear in the Firebug window containing the details of package and price IDs.

REST call details and JSON parameters for each object

To successfully create a SoftLayer object, you need to execute the proper CURL command with the correct parameters. The following examples show the parameters you can use with CURL commands, such as the header, the file name containing the JSON data, REST API URLs, and a description of key-value pairs that describe the unique properties of each object. The file name mentioned in the CURL command as @Network.json contains the JSON data required for creating this object.

1

Create network

Creating a network is the first step in the setup of ADN. All SoftLayer components need to be connected to the network in order to communicate with each other.

Rest call:

curl -H "Content-Type: application/json" --data @Network.json https://<userid>:<password>@api.softlayer.com/rest/v3.1/SoftLayer_Network/createObject

Table 1. Parameters used in Network.json
ParameterDescription
Name Name of the network
Notes Any notes about the network
Networkidentifier IP Address
CIDR 16/24
2

Create subnet

The subnet creates an address space (a group of IP addresses) inside the network. A virtual guest is assigned an IP address from an address space. Multiple subnets can be created inside a network for logical separation of address space.

Rest call:

curl -k -u '<userid>:<apikey>' -X POST -d @Subnet.json https://api.softlayer.com/rest/v3/SoftLayer_Network/<NetworkID>/createSubnet/createObject.json –i

<NetworkID> is the parameter used in the URL. This is the ID of the network inside which the subnet is created.

Table 2. Parameters used in Subnet.json
ParameterDescription
networkIdentifier This is the starting IP address of the subnet (example: "10.0.4.0").
CIDR This is the ID of the subnet mask. For example, 29 is the subnet mask that sets 8 IP addresses in the subnet. You can use either 16 or 24.
name This is the POD name in which the subnet is created (example: "dal09.pod01").
3

Create virtual guest

A virtual guest is SoftLayer terminology for a virtual machine or a virtual server. A virtual machine is the virtual version of a physical workstation computer. SoftLayer virtual guests run on SoftLayer datacenters and have their own operating system and virtual hardware resources.

Rest call:

curl -H "Content-Type: application/json" --data @VM-app.json https://<userid>:<apikey>@api.softlayer.com/rest/v3/SoftLayer_Virtual_Guest/createObject

Table 3. Parameters used in VM-app.json
ParameterDescription
hostname This is the hostname of virtual guest.
domain Domain Name (example: "ibm.com").
startCpus Total CPUs (example: "1").
datacenter Datacenter Location (example: "dal09").
hourlyBillingFlag Billed Hourly - true
operatingSystemReferenceCode Operating system (example: "UBUNTU_LATEST").
primarySubnetId Subnet ID of an existing back-end subnet.
networkVlan Public VLAN ID. This allows the virtual guest to have a public IP address.
maxSpeed1000
postInstallScriptUriThis parameter points to the location of a post provisioning script, which is executed on the server once it is provisioned. The Location (URL/URI) of this script must be accessible from the VM and should be on a secure HTTPS(SSL) location.

When the CURL command executes successfully, the following data are returned:

  {
  "accountId": 973639,
  "createDate": "2016-12-21T05:22:28-06:00",
  "domain": "ibm.com",
  "fullyQualifiedDomainName": "ADNTest1.ibm.com",
  "hostname": "ADNTest1",
  "id": 26954963,
  "lastPowerStateId": null,
  "lastVerifiedDate": null,
  "maxCpu": 1,
  "maxCpuUnits": "CORE",
  "maxMemory": 2048,
  "metricPollDate": null,
  "modifyDate": null,
  "provisionDate": null,
  "startCpus": 1,
  "statusId": 1001,
  "uuid": "f5225283-2f7b-4ab7-bab5-6ed0d064ccbb",
  "globalIdentifier": "a283bb3f-3aa9-430f-a3b4-f8a3a40feb66"
  }

Additionally, the user can check in the provisioned virtual guest under "Device List" for verification.

4

Create the Bare Metal server

SoftLayer Bare Metal servers are physical servers that can be provisioned just like virtual servers. Bare Metal servers provide raw server performance and are used for processor or disk I/O–intensive workloads.

Rest call:

curl -H "Content-Type: application/json" --data @Baremetal.json https://<userid>:<apikey>@api.softlayer.com/rest/v3/SoftLayer_Product_Order/placeOrder

Table 4. Parameters used in baremetal.json
ParameterDescription
complexType SoftLayer_Container_Product_Order_Hardware_Server

This is a mandatory parameter if verify/placeOrder methods are used.
locationData Center Location: "dallas09"
packageIdValue is 257.
This package ID specifies the following Bare Metal configuration to be used:
Intel Xeon E3-1270 v3-4 Cores-3.50 GHz-Up to 4 drives-8 GB up to 32 GB.
Package ID changes depending on the location/type/configuration of Bare Metal.
quantityValue is 1 -- A single Bare Metal is to be ordered.
hostname Hostname of Bare Metal server.
domain Domain name.
networkVlanId This is the VLAN ID of the back-end VLAN.
primarySubnetId This is the subnet ID inside the back-end VLAN. The IP to the Bare Metal is allocated from this subnet.
vlanNumber Value is 2072.
useHourlyPricing Hourly is not used in Bare Metal (value: 0).

In Table 5, each price ID denotes a chargeable hardware, a specific configuration, or a service, which were chosen during the Bare Metal ordering process.

Table 5. Price IDs
IDDescription
50357 Public Limited 500 GB Bandwidth
49759 Disk0
876 disk_controller
55 Monitoring Host Ping
57 Notification – Email and Ticket
44988 OS - CentOS 7.x (64-bit)
273 100 Mbps public and private network uplinks
21 Primary IP address
49495 RAM 8 GB
906 Remote management
58 Response -- automated notification
49515 Server
420 VPN management
418 vulnerability scanner

Note: If an incorrect price ID is given, the Rest call will fail.

For any change in hardware/configuration during Bare Metal ordering, the respective price IDs must be updated in the JSON file.

5

Create Evault storage

Evault is an enterprise-level backup storage and disaster recovery solution provided by SoftLayer.

Rest call:

curl -H "Content-Type: application/json" --data @Evault_VirtualGuest.json https://<userid>:<apikey>@api.softlayer.com/rest/v3/SoftLayer_Product_Order/placeOrder

Table 6. Parameters used in Evault_VirtualGuest.json
ParameterDescription
virtualGuests ID The ID of the virtual guest on which this service will be used.
Table 7. Price IDs
Price IDDescription
1045 The price ID for 20GB Evault disk-to-disk enterprise backup.

Create Evault storage for Bare Metal server

To create Evault storage for the Bare Metal server, use the Evault_Baremetal.json file.

6

Create object storage account

SoftLayer object storage is based on the OpenStack Swift object storage platform. It provides a redundant and highly scalable cloud storage service. To use object storage, you need to first create an object storage account.

Rest call:

curl -H "Content-Type: application/json" --data @ObjectStorage.json https:// ://<userid>:<apikey>@api.softlayer.com/rest/v3/SoftLayer_Product_Order/placeOrder

Note: Before executing the placeOrder command, first verify the order using verifyOrder (replace placeOrder in the command with verifyOrder).

Table 8. Parameters used in ObjectStorage.json
ParameterDescription
PackageId 206 is the package ID for object storage.
complexType SoftLayer_Container_Product_Order_Network_Storage_Hub
Table 9. Price IDs
Price IDDescription
16984 This is the ID for Cloud Object Storage - Standard Regional Swift API.

After you create the object storage account, you need to:

  • Create the containers
  • Utilize the containers by creating files on them

Rest call to receive authentication token (valid for only 24 hours), which is required in further requests:

curl -i -H "X-Auth-User:<user id>" -H "X-Auth-Key: <api key >" https://dal05.objectstorage.softlayer.net/auth/v1.0

Rest call to create a container using the authentication token created in the previous step:

curl -i -XPUT -H "X-Auth-Token: AUTH_tk7171f7f808cd481a89891b814adc7967" https://dal05.objectstorage.softlayer.net/v1/AUTH_4608a5ea-1df1-4ad2-9b1a-80021aadb625/tempapp

Rest call to create a file inside the container:

curl -i -XPUT -H "X-Auth-Token: AUTH_tk7171f7f808cd481a89891b814adc7967" --data-binary "Created for testing REST client" https://dal05.objectstorage.softlayer.net/v1/AUTH_4608a5ea-1df1-4ad2-9b1a-80021aadb625/tempapp/tempfile.txt

See "Managing SoftLayer Object Storage Through REST APIs" for more operations for object storage.

7

Create block storage

Block storage enables local disk performance with SAN persistence, durability, and flexibility. It allows you to create storage volumes or shares and connect them to Bare Metal or virtual servers using iSCSI connectivity.

Place order:

curl -H "Content-Type: application/json" --data @BlockStorage.json https:// ://<userid>:<apikey>@api.softlayer.com/rest/v3/SoftLayer_Product_Order/placeOrder

Table 10. Parameters used in BlockStorage.json
ParameterDescription
PackageId Value is 222. This ID is for PERFORMANCE_STORAGE_SERVICE.
locationValue is 449494. This ID is for the Dallas09 location.
osFormatType IDValue is 12. This ID is for the type Linux.
complexType SoftLayer_Container_Product_Order_Network_PerformanceStorage_Iscsi.
This is the required complex type for block storage.
Table 11. Price IDs
ParameterDescription
40672 Block storage (performance)
40682 Price ID for 20 GB storage space
40792Price ID for 100 IOPS

The Price item IDs need to be changed if different quantities are used for the storage size or the IOPS unit.

8

Authorize block storage to a virtual guest or a Bare Metal server

Each block storage must be given permission to be accessible by a virtual guest or a Bare Metal server.

REST call to allow access to virtual guest:

curl -H "Content-Type:application/json" --data @BlockStorage_Auth.json https://<userid>:<password>@api.softlayer.com/rest/v3.1/ SoftLayer_Network_Storage_Iscsi/<ISCSI_BlocKStorageID>/allowAccessFromVirtualGuest

The parameter used in the URL, <ISCSI_BlocKStorageID>, is the ID of the ISCSI block storage that needs access to the virtual guest.

Table 12. Parameters used in BlockStorage_Auth.json
ParameterDescription
id ID of virtual guest to which the storage block is to be allowed access.

REST call to allow access to Bare Metal:

curl -H "Content-Type:application/json" --data @JSON-Payload-file.json https://<userid>:<password>@api.softlayer.com/rest/v3.1/ SoftLayer_Network_Storage_Iscsi/<ISCSI_BlocKStorageID>/allowAccessFromHardware

The parameter used in the URL, <ISCSI_BlocKStorageID>, is the ID of the ISCSI block storage that needs access to the virtual guest.

Table 13. Parameters used in BlockStorage_Auth.json
ParameterDescription
id The ID of a Bare Metal server.
9

Order NetScaler VPX Load Balancer

Citrix NetScaler is a powerful web application delivery appliance and load balancer.

Rest call:

curl -H "Content-Type: application/json" --data @Netscaler.json https://<userid>:<apikey>@api.softlayer.com/rest/v3/SoftLayer_Product_Order/placeOrder

Note: Before executing the placeOrder command, first verify the order using the verifyOrder Command (replace placeOrder in the command with verifyOrder).

Upon successful execution of this command, order information for JSON payload containing all details of the order will be returned.

Verify successful provisioning of NetScaler from SoftLayer portal:

  1. Log into SoftLayer portal .
  2. Go to the device list. The Ordered NetScaler device should be listed.
  3. Click to open the device. (The URL will look like the following: https://control.softlayer.com/devices/details/<id>/applicationDeliveryController.)
  4. Choose Actions > Manage Device. The user should be able to manage the device.
  5. Verify that private IP, correct public VLAN, and the correct number of IPs requested have been assigned.
Table 14. Parameters used in JSON payload
ParameterDescription
location Data Center location: "DALLAS09"
packageId Package ID for NetScaler VPX: 192
Back-end VLAN Back-end VLAN is denoted by the following JSON format:

{"primaryBackendNetworkComponent": {"networkVlan": {"primarySubnet": {"id": <ID>}}}.

This is the ID of the back-end subnet of the back-end network.
Public VLAN
The following JSON format denotes the public VLAN:

"primaryNetworkComponent": {"networkVlan": {"id": <ID>}}}

This is the ID of the public VLAN.
Table 15. Price IDs
ParameterDescription
44964 Price ID for Citrix NetScaler VPX 10.5 10Mbps Standard.
(This ID will vary, depending upon the type of NetScaler Configuration chosen.)
17238 Price ID for two static public IP addresses (which will vary, depending on the number of IPs chosen).

Questions and answers

The NetScaler VPX ordering process requires that the user answer questions related to the use of IP addresses. You can find detailed explanations of these questions using the following command:

curl https://<userid>:<apikey>@api.softlayer.com/rest/v3oftLayer_Product_Item_Category/53/getQuestions

(53 is the category ID for public secondary static IP addresses.)

Brief explanations of the questions are shown in Table 16. Answers to these questions are in the JSON payload in NetScaler.json

Table 16. Question details
Question IDDescription
9 The name of the contact person.
10 The job title of the contact person.
11 The email address of the contact person.
12 The phone number of the contact person.
13 The flag indicating that the user confirms that the contact information is current and accurate (can be 0 or 1).
14 The number of IP addresses expected to be used within the next 30 days.
15 The number of IP addresses expected to be used within the next 12 months.
16 A brief explanation of the reason(s) that additional IPs are needed.

Conclusion

Infrastructure setup and configuration is a time-consuming process. SoftLayer APIs allow you to introduce some automation into that process. SoftLayer provides a uniform and standard API library that can be accessed through various methods and tools, and is transparent to the SoftLayer portal. In this tutorial, you have learned the steps to creating an ADN network that's ready for application deployment. You have also explored numerous ways of making REST API calls to SoftLayer Cloud, and looked at commands and scripts that automate an entire ADN setup.

In addition, we have showed you how ADN serves two purposes: (1) It defines a root IP address range to use for future private IP address allocation, and (2) it gives you a container for grouping servers that need to communicate with each other using their private IPs.

Acknowledgements

We would like to thank the following people for their support and assistance:

Dinakaran Joseph—Distinguished Engineer, Cloud

Senthilkumar Vimalraj—Infrastructure Specialist, GTS Labs

Nalini M—Senior Developer, Cognitive & Cloud

Sudhanva Kulkarni—Application Developer, Cloud

Vivekanandan Subramanian—Executive Architect, Cloud


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Cloud computing
ArticleID=1048182
ArticleTitle=Configure SoftLayer components for use with Account Defined Network
publish-date=08082017