Zend_Service_Rackspace_Files
Zend_Service
Programmer's Reference Guide

Zend_Service_Rackspace_Servers

Overview

The Zend_Service_Rackspace_Servers is a class that provides a simple API to manage the » Rackspace Cloud Servers. Using this class you can:

  • Create new servers

  • List and get information on each server

  • Delete a server

  • Manage the public/private IP addresses of a server

  • Resize the server capacity

  • Reboot a server

  • Create new images for a server

  • Manage the backup of a server

  • Create a group of server to share the IP addresses for High Availability architecture

Terminology

A server is a virtual machine instance in the Cloud Servers system. Flavor and image are requisite elements when creating a server.

A server is managed using the the class Zend_Service_Rackspace_Servers_Server.

A flavor is an available hardware configuration for a server. Each flavor has a unique combination of disk space, memory capacity and priority for CPU time.

An image is a collection of files used to create or rebuild a server. Rackspace provides a number of pre-built OS images by default. You may also create custom images from cloud servers you have launched. These custom images are useful for backup purposes or for producing “gold” server images if you plan to deploy a particular server configuration frequently.

An image is managed using the the class Zend_Service_Rackspace_Servers_Image.

A backup schedule can be defined to create server images at regular intervals (daily and weekly). Backup schedules are configurable per server.

Public IP addresses can be shared across multiple servers for use in various high availability scenarios. When an IP address is shared to another server, the cloud network restrictions are modified to allow each server to listen to and respond on that IP address (you may optionally specify that the target server network configuration be modified). Shared IP addresses can be used with many standard heartbeat facilities (e.g. keepalived) that monitor for failure and manage IP failover.

A shared IP group is a collection of servers that can share IPs with other members of the group. Any server in a group can share one or more public IPs with any other server in the group. With the exception of the first server in a shared IP group, servers must be launched into shared IP groups. A server may only be a member of one shared IP group.

A shared IP group is managed using the the class Zend_Service_Rackspace_Servers_SharedIpGroup.

Quick Start

To use this class you have to pass the username and the API's key of Rackspace in the construction of the class.

  1. $user = 'username';
  2. $key  = 'secret key';
  3.  
  4. $rackspace = new Zend_Service_Rackspace_Servers($user,$key);

To create a new server you can use the createServer method.

  1. $data = array (
  2.     'name'     => 'test',
  3.     'imageId'  => '49',
  4.     'flavorId' => '1',
  5. );
  6.  
  7. $server= $rackspace->createServer($data);
  8.  
  9. if (!$rackspace->isSuccessful()) {
  10.     die('ERROR: '.$rackspace->getErrorMsg());
  11. }
  12.  
  13. printf("Server name    : %s\n",$server->getName());
  14. printf("Server Id      : %s\n",$server->getId());
  15. printf("Admin password : %s\n",$server->getAdminPass());

This example create a server with name test, imageId 49, and flavorId 1. The attributes name, imageId and flavorId are required to create a new server. The result of createServer is an instance of Zend_Service_Rackspace_Servers_Server.

To get the public and private IP addresses of a server you can use the getServerIp method.

  1. $id  = '20054631';
  2. $ips = $rackspace->getServerIp($id);
  3.  
  4. if (!$rackspace->isSuccessful()) {
  5.     die('ERROR: '.$rackspace->getErrorMsg());
  6. }
  7.  
  8. echo "Private IPs:\n";
  9. print_r($ips['private']);
  10. echo "Public IPs:\n";
  11. print_r($ips['public']);

This example get the IP addresses of the server with Id 20054631. The result of getServerIp is an associative arrays with keys 'private' and 'public' contains all the private IP addresses and the public IP addresses of the server.

To get the list of all the available servers you can use the listServers method.

  1. $servers= $rackspace->listServer(true);
  2.  
  3. if (!$rackspace->isSuccessful()) {
  4.     die('ERROR: '.$rackspace->getErrorMsg());
  5. }
  6.  
  7. foreach ($servers as $srv) {
  8.     printf("Name      : %s\n",$srv->getName());
  9.     printf("Server Id : %s\n",$srv->getId());
  10.     printf("Image  Id : %s\n",$srv->getImageId());
  11.     printf("Flavor Id : %s\n",$srv->getFlavorId());
  12.     printf("Status    : %s (%d\%)\n",$srv->getStatus(),$srv->getProgress());
  13. }

Available Methods

changeBackupSchedule ( string $id, string $weekly, string $daily )

This operation creates a new backup schedule or updates an existing backup schedule for the specified server. Return true in case of success, false in case of error.

$id is the ID of the server

$weekly, the day of the week for the backup (for instance "THURSDAY")

$daily, specify the hours for the backup (for instance "H_0400_0600")

changeServerName ( string $id, string $name )

Change the name of a server. Return true in case of success, false in case of error.

$id is the ID of the server

$name is an optional parameter that specify the new name of the server

changeServerPassword ( string $id, string $password )

Change the admin password of a server. Return true in case of success, false in case of error.

$id is the ID of the server

$password is an optional parameter that specify the new admin password of the server

confirmResizeServer ( string $id )

Confirm the resize of a server. During a resize operation, the original server is saved for a period of time to allow roll back if there is a problem. Once the newly resized server is tested and has been confirmed to be functioning properly, use this operation to confirm the resize. After confirmation, the original server is removed and cannot be rolled back to. All resizes are automatically confirmed after 24 hours if they are not explicitly confirmed or reverted. Return true in case of success, false in case of error.

$id is Id of the server.

createImage ( string $serverId,string $name )

Create an image from a server. Return a new instance of Zend_Service_Rackspace_Servers_Image. In case of error the return is false.

$serverId is the Id of the server to use to create the image.

$name, is the name of image to create

createSharedIpGroup ( string $name, string $serverId )

This operation creates a new shared IP group. Please note, on a create request, the shared IP group can be created empty or can be initially populated with a single server. Return the shared IP group as instance of Zend_Service_Rackspace_Servers_SharedIpGroup In case of error the return is false.

$name is the name of the shared IP group to create.

$serverId is the Id of the server.

createServer ( array $data, $metadata=array(),$files=array() )

Create a server with the attributes specified in $data. You can specify also optional parameters: metadata and files. Metadata is an array contains key/value of metadata related to the server and files is an array contains the paths of some files to upload into the server. The syntax used for the uploading of the files is 'serverPath' => 'localPath'. Return a new instance of Zend_Service_Rackspace_Servers_Server. In case of error the return is false.

$data contains the parameters for the server. The required attributes to create a new server are:

  • name, contains the name of the server

  • flavorId, contains the flavor's Id to use

  • imageId, contains the image's Id to use

$metadata, contains the array of metadata information

$files, contains the path of the files to upload in the server using the syntax 'serverPath' => 'localPath'.

disableBackupSchedule ( string $id )

Disable the backup of a server. Return true in case of success, false in case of error.

$id is the Id of the server.

deleteImage ( string $id )

Delete a image. Return true in case of success, false in case of error.

$id is the Id of the image.

deleteSharedIpGroup ( string $id )

Delete a shared IP group. Return true in case of success, false in case of error.

$id is the Id of the shared IP group.

deleteServer ( string $id )

Delete a server. Return true in case of success, false in case of error.

$id is the Id of the server.

getBackupSchedule ( string $id )

Return the backup schedule of a server. The return is an associative array with the following values: enabled, weekly, daily. In case of error the return is false.

$id is the Id of the server.

getFlavor ( string $flavorId )

Return the information about a flavor. The return is an associative array with the following values: id, ram, disk, name. In case of error the return is false.

$flavorId is the Id of the flavor.

getImage ( string $id )

Return an image as instance of Zend_Service_Rackspace_Servers_Image. In case of error the return is false.

$id is the Id of the image.

getSharedIpGroup ( string $id )

Return the shared IP group as instance of Zend_Service_Rackspace_Servers_SharedIpGroup In case of error the return is false.

$id is the Id of the shared IP group.

getServer ( string $id )

Return the server specified by the Id as instance of Zend_Service_Rackspace_Servers_Server. In case of error the return is false.

$id is Id of the server.

getServerIp ( string $id )

Return the public and private IP addresses of a server. Return an associative array contains the key 'public' and 'private' for the IP addresses. In case of error the return is false.

$id is Id of the server.

getServerPrivateIp ( string $id )

Return the private IP addresses of the server. Return an associative array contains the IP addresses. In case of error the return is false.

$id is Id of the server.

getServerPublicIp ( string $id )

Return the public IP addresses of the server. Return an associative array contains the IP addresses. In case of error the return is false.

$id is Id of the server.

listFlavors ( boolean $details=false )

Return all the available flavors as associative array. In case of error the return is false.

If $details is true return a detailed list, if is false return only the name and the Id of the flavor.

listImages ( boolean $details=false )

Return all the available images as instance of Zend_Service_Rackspace_Servers_ImageList In case of error the return is false.

If $details is true return a detailed list, if is false return only the name and the Id of the Image.

listServer ( boolean $details=false )

Return all the available servers with a new instance of Zend_Service_Rackspace_Servers_ServerList. In case of error the return is false.

If $details is true return a detailed list, if is false return only the name and the Id of the server.

listSharedIpGroups ( boolean $details=false )

Return all the shared IP groups as instance of Zend_Service_Rackspace_Servers_SharedIpGroupList In case of error the return is false.

If $details is true return a detailed list, if is false return only the name and the Id of the shared IP group.

rebootServer ( string $id, boolean $hard=false )

Reboot a server. Return true in case of success, false in case of error.

$id is Id of the server.

If $hard is false (default) the server is rebooted in soft mode. That means the operating system is signaled to restart, which allows for a graceful shutdown of all processes. If $hard is true the server is rebooted in hard mode. A hard reboot is the equivalent of power cycling the server.

rebuildServer ( string $id, string $imageId )

Rebuild a server. The rebuild function removes all data on the server and replaces it with the specified image, server's Id and IP addresses will remain the same. Return true in case of success, false in case of error.

$id is Id of the server.

$imageId is the new Image Id of the server.

resizeServer ( string $id, string $flavorId )

Resize a server. The resize function converts an existing server to a different flavor, in essence, scaling the server up or down. The original server is saved for a period of time to allow rollback if there is a problem. All resizes should be tested and explicitly confirmed, at which time the original server is removed. All resizes are automatically confirmed after 24 hours if they are not explicitly confirmed or reverted. Return true in case of success, false in case of error.

$id is Id of the server.

$flavorId is the new flavor Id of the server.

revertResizeServer ( string $id )

Revert the resize of a server. During a resize operation, the original server is saved for a period of time to allow for roll back if there is a problem. If you determine there is a problem with a newly resized server, use this operation to revert the resize and roll back to the original server. All resizes are automatically confirmed after 24 hours if they have not already been confirmed explicitly or reverted. Return true in case of success, false in case of error.

$id is Id of the server.

shareIpAddress ( string $id, string $ip, string $groupId, boolean $configure=true )

Share an IP address for a server. Return true in case of success, false in case of error.

$id is Id of the server.

$ip is the IP address to share.

$groupId is the group Id to use.

If $configure attribute is set to true, the server is configured with the new address, though the address is not enabled. Note that configuring the server does require a reboot.

unshareIpAddress ( string $id, string $ip )

Unshare an IP address for a server. Return true in case of success, false in case of error.

$id is Id of the server.

$ip is the IP address to share.

updateServer ( string $id,string $name=null,string $password=null )

Change the name or/and the admin password of a server. In case of error the return is false.

$id is the ID of the server

$name is an optional parameter that specify the new name of the server

$password is an optional parameter that specify the new admin password of the server

Examples

Example #1 Authenticate

Check if the username and the key are valid for the Rackspace authentication.

  1. $user = 'username';
  2. $key  = 'secret key';
  3.  
  4. $rackspace = new Zend_Service_Rackspace_Servers($user,$key);
  5.  
  6. if ($rackspace->authenticate()) {
  7.     printf("Authenticated with token: %s",$rackspace->getToken());
  8. } else {
  9.     printf("ERROR: %s",$rackspace->getErrorMsg());
  10. }

Example #2 Create a server with metadata information and upload of a file

Create a server with some metadata information and upload the file build.sh from the local path /home/user to the remote path /root.

  1. $data = array (
  2.     'name'     => 'test',
  3.     'imageId'  => '49',
  4.     'flavorId' => '1',
  5. );
  6. $metadata = array (
  7.     'foo' => 'bar',
  8. );
  9. $files = array (   
  10.     '/root/build.sh' => '/home/user/build.sh',
  11. );
  12. $server= $rackspace->createServer($data,$metadata,$files);
  13.  
  14. if (!$rackspace->isSuccessful()) {
  15.     die('ERROR: '.$rackspace->getErrorMsg());
  16. }
  17.  
  18. $publicIp= $server->getPublicIp();
  19.  
  20. printf("Server name    : %s\n",$server->getName());
  21. printf("Server Id      : %s\n",$server->getId());
  22. printf("Public IP      : %s\n",$publicIp[0]);
  23. printf("Admin password : %s\n",$server->getAdminPass());

Example #3 Reboot a server

Reboot a server in hard mode (is the equivalent of power cycling the server).

  1. $flavors= $rackspace->rebootServer('server id',true)
  2.  
  3. if (!$rackspace->isSuccessful()) {
  4.     die('ERROR: '.$rackspace->getErrorMsg());
  5. }
  6.  
  7. echo "The server has been rebooted successfully";

Example #4 List all the available flavors

List all the available flavors with all the detailed information.

  1. $flavors= $rackspace->listFlavors(true);
  2.  
  3. if (!$rackspace->isSuccessful()) {
  4.     die('ERROR: '.$rackspace->getErrorMsg());
  5. }
  6.  
  7. print_r($flavors);
Zend_Service_Rackspace_Files
Zend_Service
Programmer's Reference Guide