Getting started with CCIs

<p>In the context of the SoftLayer API, SoftLayer CloudLayer Computing Instances(CCIs) are represented by <a href=https://sldn.softlayer.com/refe

In the context of the SoftLayer API, SoftLayer CloudLayer Computing Instances(CCIs) are represented by SoftLayer_Virtual_Guest objects. The SoftLayer_Virtual_Guest service allows for interaction with a specific CCI and you are able to interact with all CCIs on your account through the SoftLayer_Account service.

Creating

Ordering new CCIs is accomplished through SoftLayer_Virtual_Guest::createObject.
First, a SoftLayer_Virtual_Guest template object is created that contains the details of the CCI. Every CCI template object will need, at minimum, the following properties defined:

hostname - Hostname of the new CCI
domain - Domain name of the new CCI
startCpus - Number of processing cores
maxMemory - Memory allocation in MB
hourlyBillingFlag - Set true for hourly billing, false for monthly
operatingSystemReferenceCode - Code to specify which OS to install
localDiskFlag - Setting to true will configure a CCI with local disks, false for SAN disks

$virtualGuestClient = SoftLayer_SoapClient::getClient('SoftLayer_Virtual_Guest', null, $user, $key);
$virtualGuestTemplate = new stdClass();
$virtualGuestTemplate->hostname = 'test1';
$virtualGuestTemplate->domain = 'example.com';
$virtualGuestTemplate->startCpus = 1;
$virtualGuestTemplate->maxMemory = 1024;
$virtualGuestTemplate->hourlyBillingFlag = true;
$virtualGuestTemplate->operatingSystemReferenceCode = 'UBUNTU_LATEST';
$virtualGuestTemplate->localDiskFlag = false;
 
$result = $virtualGuestClient->createObject($virtualGuestTemplate);
print_r($result);

All options for CCI ordering can be retrieved with SoftLayer_Virtual_Guest::getCreateObjectOptions.
The createObject() method incurs charges on the account so it is best to test CCI creation without causing an order to be placed with SoftLayer_Virtual_Guest::generateOrderTemplate to generate an order object. The SoftLayer_Container_Product_Order returned by this method can be passed into SoftLayer_Product_Order::verifyOrder which informs of any issues that would prevent the order from processing.

$orderClient = SoftLayer_SoapClient::getClient('SoftLayer_Product_Order', Null, $user, $key);
$orderContainer = $virtualGuestClient->generateOrderTemplate($virtualGuestTemplate);
print_r($orderClient->verifyOrder($orderContainer);

Listing

A list of all CloudLayer Computing Instances can be gathered from the SoftLayer_Account service with the SoftLayer_Account::getVirtualGuests method. This method returns an array of SoftLayer_Virtual_Guest data type objects.

$accountClient = SoftLayer_SoapClient::getClient('SoftLayer_Account', Null, $user, $key);
$virtualGuests = $accountClient->getVirtualGuests();
print_r($virtualGuests);

This full listing is often used for retrieving information about all CCIs on an account and is also useful when searching for a specific CCI whos ID is unknown.

$accountClient = SoftLayer_SoapClient::getClient('SoftLayer_Account', Null, $user, $key);
$virtualGuests = $accountClient->getVirtualGuests();
foreach ($virtualGuests as $virtualGuest) {
    if ($virtualGuest->hostname == "server1") {
        $serverId = $virtualGuest->id;
    }
}

Details

To get information about a specific CCI we can use SoftLayer_Virtual_Guest::getObject which returns a SoftLayer_Virtual_Guest object. Object masks can be used to include data outside of SoftLayer_Virtual_Guest's local properties. Below is an example of using getObject on the SoftLayer_Virtual_Guest service with an object mask which provides the passwords for the operating system installed on the server.

$guestClient = SoftLayer_SoapClient::getClient('SoftLayer_Virtual_Guest', $id, $user, $key);
$objectMask = "mask[id, hostname, domain, operatingSystem[passwords]]"
$guestClient->setObjectMask($objectMask);
$virtualGuest = $guestClient->getObject();
print_r($virtualGuest);

Since we have also defined a number of local properties, notice the output only includes the limited set of local properties defined in the mask in addition to the relational properties brought in by the object mask.

Canceling

Canceling CCIs can be done by pulling the ID from the SoftLayer_Account service. In this example we pull all virtual guests from the account and use the hostname to parse the specific guest we want to cancel. This should be used with caution as the hostname of a virtual guest is not unique.
SoftLayer_Virtual_Guest::deleteObject

$guestClient = SoftLayer_SoapClient::getClient('SoftLayer_Virtual_Guest', $serverId, $user, $key);
$result = $guestClient->deleteObject();
print_r($result);

This method immediately cancels the computing instance with the specified ID.
Note: Pausing an instance with SoftLayer_Virtual_Guest::pause will not stop billing. An instance must be cancelled/destroyed for billing to cease.

Rebooting

Power cycling a CCI can be done two ways: