Difference between revisions of "Advanced Cloud Hosting/Cloud API"

From XMission Wiki
Jump to: navigation, search
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
If you find yourself with traffic to your website and consistently trying to log in to your Control Panel to adjust your servers RAM to compensate for the heavy load. We have a solution that may help you get some sleep.
+
{{Archived}}
−
 
+
The RESTful API is one of the most useful and more interesting features of our Cloud Infrastructure service. With the ability to expose nearly all the features of your control panel the API will definitely help you get some 'REST'.   
−
Cloud Infrastructure API can Automatically Resize your Server. The RESTful API is on of the most useful and more interesting features of our Cloud Infrastructure service. With the ability to expose nearly all the features of your control panel the API will definitely help you get some 'REST'.   
 
  
 
The Cloud Infrastructure RESTful API is well documented and available to all Cloud Infrastructure and Cloud Server subscribers. You can read the full documentation here:
 
The Cloud Infrastructure RESTful API is well documented and available to all Cloud Infrastructure and Cloud Server subscribers. You can read the full documentation here:
Line 7: Line 6:
  
  
−
Below is a PHP script that you can add to a cron job - this one we will run every minute. The timing is up to completely up to you and you can change it any time you want. A shorter time makes the server more sensitive to traffic and load, however it also puts additional load on the server itself.
+
==Accessing a Resource==
 +
A PACI resource is accessed by sending an HTTPS request to a PACI server. When the server receives a request, it processes it accordingly (performs actions or retrieves data) and sends back a response that can contain the data that you requested, an operation status code, or an error messate. All PACI resources are accessed at the following URL (referred to as ''baseURL'')
  
−
<code><pre>
+
<code><pre>https://{ip_address | hostname}:port/paci/version</pre></code>
−
#!/usr/bin/php -q
+
where:
−
<?php
+
#'''ip_address | hostname''' is the PACI server IP address or hostname.
−
// Script for resizing server memory using the XMission Cloud Infrastructure API
+
#'''port''' is the port number on which the server is listening for REST requests
 +
#'''paci''' must be typed exactly as shown
 +
#'''version''' is the API version number
  
−
// Configuration
+
For our resource the ''baseURL'' will use the following:
 +
<code><pre>https://api.cloud.xmission.com:4464/paci/v1.0/</pre></code>
  
−
// Memory tolerances
 
−
define("LOWER_RAM_LIMIT", 256); # The lowest amount of memory for the server
 
−
define("UPPER_RAM_LIMIT", 1024); # The highest amount of memory for the server
 
−
define("LOWER_TOLERANCE", 0.25); # Decrease the memory if ratio is below this
 
−
define("UPPER_TOLERANCE", 0.8); # Increase the memory if ratio is above this
 
−
define("MEMORY_INCREMENT", 256); # Increment the memory by this amount
 
  
−
// The RESTful API
+
==Server Management==
−
define("API_URL", "https://api.cloud.xmission.com:4464/paci/v1.0/");
+
Using this API can come in handy for various types of resource information for example you can use the API to list your current server, configure your server, even stop and start lets take a look at a few basic commands.  
  
−
// Your username and password for the API (same as your login to https://cp.xmission.com)
+
===List your current servers===
−
define("USER", '<YOUR_USER_NAME>');
+
Use this request to obtain the list of servers owned by the current user
−
define("PASS", '<YOUR_PASSWORD>');
+
<code><pre>GET https://api.cloud.xmission.com:4464/paci/v1.0/ve</pre></code>
  
−
// The name of the server - should match Control Panel's name of the server
+
A sample out put would list your current servers.
−
define("VPS_HOST_NAME", 'webserver01');
+
<code><pre>
−
// Check RAM usage
+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
−
error_log("resize_check: Checking server RAM usage.");
+
<ve-list>
 +
    <ve-info description="XMission minecraft server" state="STARTED" name="minecraft" subscription-id="1003209"/>
 +
</ve-list>
 +
</pre></code>
  
−
// Get the raw memory output
 
−
$raw_output = shell_exec("free -o -m");
 
−
$memory_lines = explode("\n", $raw_output);
 
−
$current_memory = preg_split("/[\s:]+/",$memory_lines[1]);
 
  
−
// $current_memory[1] is total, $current_memory[2] is used
+
===More  specific server info===
−
$current_memory_load = $current_memory[2] / $current_memory[1];
+
If you want to be more specific and obtain information about a specific server you can add the server name like this:
−
error_log("resize_check: Current memory use is: " . $current_memory_load) ;
+
<code><pre>GET https://api.cloud.xmission.com:4464/paci/v1.0/ve/server1</pre></code>
  
−
// Is the current memory load in tolerance?
+
A sample out put will look like this:
−
if (LOWER_TOLERANCE > $current_memory_load) {
+
<code><pre>
−
    error_log("resize_check: Current memory usage of $current_memory_load below tolerance. Resizing.");
+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
−
 
+
<ve>
−
    $current_memory_setting = get_mem();
+
     <id>296</id>
−
    error_log("resize_check: Current memory setting is: " . $current_memory_setting) ;
+
     <uuid>3c1c50b1.13d794f9065._7ff0</uuid>
−
 
+
     <hnId>14</hnId>
−
    if ($current_memory_setting > LOWER_RAM_LIMIT) {
+
     <customer-id>1000001</customer-id>
−
        decrease_memory($current_memory_setting, MEMORY_INCREMENT);
+
     <name>server1</name>
−
        error_log("resize_check: Decreased memory by " . MEMORY_INCREMENT ) ;
+
     <description>Testing Server</description>
−
    } else {
+
     <subscription-id>100001</subscription-id>
−
        error_log("resize_check: Could not decrease memory more, already at lowest limit.") ;
+
     <cpu number="4" power="1500"/>
−
     }
+
     <ram-size>6400</ram-size>
−
 
+
    <bandwidth>10000</bandwidth>
−
     exit(0);
+
     <ve-disk created="true" id="0" local="true" size="25"/>
−
} else if ($current_memory_load > UPPER_TOLERANCE) {
+
     <platform>
−
    error_log("resize_check: Current memory usage of $current_memory_load above tolerance. Resizing.");
+
        <template-info name="ubuntu-12.04-x86_64"/>
−
 
+
        <os-info type="ubuntu-12.04-x64" technology="CT"/>
−
     $current_memory_setting = get_mem();
+
    </platform>
−
     error_log("resize_check: Current memory setting is: " . $current_memory_setting) ;
+
     <network private-ip="10.0.0.0/8">
−
 
+
        <public-ip chunk-ref="1" id="269" address="123.123.123.123/24" gateway="123.123.123.1"/>
−
     if ($current_memory_setting < UPPER_RAM_LIMIT) {
+
     </network>
−
        increase_memory($current_memory_setting, MEMORY_INCREMENT);
+
     <state>STARTED</state>
−
        error_log("resize_check: Increased memory by " . MEMORY_INCREMENT ) ;
+
     <primary-disk-id>0</primary-disk-id>
−
     } else {
+
     <template-id>12</template-id>
−
        error_log("resize_check: Could not increase memory more, already at highest limit.") ;
+
     <admin login="root" password="[hidden]"/>
−
    }
+
     <steady-state>STARTED</steady-state>
−
 
+
</ve>
−
    exit(0);
 
−
} else {
 
−
    error_log("resize_check: Current memory usage of $current_memory_load in tolerance. Exiting.");
 
−
    exit(0);
 
−
}
 
−
// Helper Functions
 
−
function get_mem() {
 
−
     $r_xml = req_rest('GET', VPS_HOST_NAME);
 
−
    return ((string) $r_xml->{'ram-size'}[0]);
 
−
}
 
−
 
 
−
function increase_memory($current, $increase_by) {
 
−
     $size_to_increase_to = $current + $increase_by;
 
−
    error_log("resize_check: setting memory to: " . $size_to_increase_to);
 
−
    $xml = '<?xml version="1.0" encoding="UTF-8"?>' .
 
−
     "<reconfigure-ve><ram-size>$size_to_increase_to</ram-size></reconfigure-ve>";
 
−
 
 
−
     $result = req_rest("PUT", VPS_HOST_NAME, $xml);
 
−
    return $result;
 
−
}
 
−
 
 
−
function decrease_memory($current, $decrease_by) {
 
−
    $size_to_decrease_to = $current - $decrease_by;
 
−
    error_log("resize_check: setting memory to: " . $size_to_decrease_to);
 
−
    $xml = '<?xml version="1.0" encoding="UTF-8"?>' .
 
−
     "<reconfigure-ve><ram-size>$size_to_decrease_to</ram-size></reconfigure-ve>";
 
−
 
 
−
     $result = req_rest("PUT", VPS_HOST_NAME, $xml);
 
−
    return $result;
 
−
}
 
−
 
 
−
function req_rest($method, $get_params = "", $parameters = "", $additional_headers = "") {
 
−
    $process = curl_init();
 
−
     curl_setopt($process, CURLOPT_HTTPHEADER, array('Content-Type: application/xml', $additional_headers));
 
−
     //curl_setopt($process, CURLOPT_VERBOSE, 1);
 
−
     curl_setopt($process, CURLOPT_SSL_VERIFYPEER, 0);
 
−
    curl_setopt($process, CURLOPT_SSL_VERIFYHOST, 0);
 
−
     //curl_setopt($process, CURLOPT_HEADER, 1);
 
−
     curl_setopt($process, CURLOPT_USERPWD, USER. ":" . PASS);
 
−
    curl_setopt($process, CURLOPT_TIMEOUT, 30);
 
−
 
 
−
    switch($method) {
 
−
        case 'POST':
 
−
            curl_setopt($process, CURLOPT_POST, 1);
 
−
            curl_setopt($process, CURLOPT_POSTFIELDS, array($parameters));
 
−
            break;
 
−
        case 'PUT':
 
−
            curl_setopt($process, CURLOPT_CUSTOMREQUEST, "PUT");
 
−
            curl_setopt($process, CURLOPT_POSTFIELDS, $parameters);
 
−
        case 'GET':
 
−
            default:
 
−
            break;
 
−
     }
 
−
 
 
−
    curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
 
−
    curl_setopt($process, CURLOPT_URL, API_URL . "ve/" . $get_params);
 
−
    $return = curl_exec($process);
 
−
    curl_close($process);
 
−
 
 
−
    if (strpos($return, '<') !== false) {
 
−
        $xml = new SimpleXmlElement($return);
 
−
        return $xml;
 
−
    } else {
 
−
        return $return;
 
−
    }
 
−
}
 
 
</pre></code>
 
</pre></code>
  
−
Here is some explanation of what this will do:
+
Here you can see it shows you all relative information about the server including the number of CPUs, CPU Power, Ram, IP address and much more.  
−
:Lines 8 - 12 define memory limits
 
−
<pre>
 
−
define("LOWER_RAM_LIMIT", 256); # The lowest amount of memory for the server
 
−
define("UPPER_RAM_LIMIT", 1024); # The highest amount of memory for the server
 
−
define("LOWER_TOLERANCE", 0.25); # Decrease the memory if ratio is below this
 
−
define("UPPER_TOLERANCE", 0.8); # Increase the memory if ratio is above this
 
−
define("MEMORY_INCREMENT", 256); # Increment the memory by this amount
 
−
</pre>
 
−
 
 
−
:Line 15 defines the API URL, and should be fine for all XMission Cloud Services customers
 
−
<pre>
 
−
define("API_URL", "https://api.cloud.xmission.com:4464/paci/v1.0/");
 
−
</pre>
 
−
 
 
−
:Lines 18 and 19 are the user name and password for the control panel <https://cp.xmission.com>
 
−
<pre>
 
−
define("USER", '<YOUR_USER_NAME>');
 
−
define("PASS", '<YOUR_PASSWORD>');
 
−
</pre>
 
−
 
 
−
:Line 22 is the hostname of the VPS
 
−
<pre>
 
−
define("VPS_HOST_NAME", 'webserver01');
 
−
</pre>
 
−
 
 
−
:Lines 28 through 35 gather data about the current memory load on the VPS.
 
−
<pre>
 
−
$memory_lines = explode("\n", $raw_output);
 
−
$current_memory = preg_split("/[\s:]+/",$memory_lines[1]);
 
−
 
 
−
// $current_memory[1] is total, $current_memory[2] is used
 
−
$current_memory_load = $current_memory[2] / $current_memory[1];
 
−
error_log("resize_check: Current memory use is: " . $current_memory_load) ;
 
−
 
 
−
// Is the current memory load in tolerance?
 
−
</pre>
 
  
−
:Lines 38 through 69 are the logic for keeping the server memory within boundaries set in the configuration.
+
Many more useful command can be used as well - more common would be to start or stop your server.  
−
<pre>
 
  
−
    $current_memory_setting = get_mem();
 
−
    error_log("resize_check: Current memory setting is: " . $current_memory_setting) ;
 
  
−
    if ($current_memory_setting > LOWER_RAM_LIMIT) {
+
===Start / Stop your Server===
−
        decrease_memory($current_memory_setting, MEMORY_INCREMENT);
+
<code><pre>PUT https://api.cloud.xmission.com:4464/paci/v1.0/ve/server1/stop</pre></code>
−
        error_log("resize_check: Decreased memory by " . MEMORY_INCREMENT ) ;
 
−
    } else {
 
−
        error_log("resize_check: Could not decrease memory more, already at lowest limit.") ;
 
−
    }
 
  
−
    exit(0);
+
A sample output would be:
−
} else if ($current_memory_load > UPPER_TOLERANCE) {
+
<code><pre>VE START initiated</pre></code>
−
    error_log("resize_check: Current memory usage of $current_memory_load above tolerance. Resizing.");
 
  
−
    $current_memory_setting = get_mem();
+
There is so much more you can do with this API including adjusting your server at peak times to compensate for your server load, and then readjusting them back during non peak times.  
−
    error_log("resize_check: Current memory setting is: " . $current_memory_setting) ;
 
  
−
    if ($current_memory_setting < UPPER_RAM_LIMIT) {
+
We have a great blog post regarding this API located on Transmission XMission's Company Journal
−
        increase_memory($current_memory_setting, MEMORY_INCREMENT);
+
:[http://transmission.xmission.com/2013/08/19/use-the-cloud-infrastructure-api-to-automatically-resize-your-server Use the Cloud Infrastructure API to Automatically Resize Your Server]
−
        error_log("resize_check: Increased memory by " . MEMORY_INCREMENT ) ;
 
−
    } else {
 
−
        error_log("resize_check: Could not increase memory more, already at highest limit.") ;
 
−
    }
 
  
−
    exit(0);
+
This documentation is to be used as a guide. Your server will require different settings to optimize your traffic and this code is not perfect. We encourage you to customize it to fit your needs, or write it in a language of your choice. Remember to refer to the documentation.
−
} else {
 
−
    error_log("resize_check: Current memory usage of $current_memory_load in tolerance. Exiting.");
 
−
    exit(0);
 
−
}
 
−
</pre>
 
  
−
:Lines 73 though 76 provide
+
[[Category: Hosting Archives]]

Latest revision as of 13:51, 25 September 2018

Archives.png

The RESTful API is one of the most useful and more interesting features of our Cloud Infrastructure service. With the ability to expose nearly all the features of your control panel the API will definitely help you get some 'REST'.

The Cloud Infrastructure RESTful API is well documented and available to all Cloud Infrastructure and Cloud Server subscribers. You can read the full documentation here:

http://download.pa.parallels.com/poa/5.4/doc/pdf/POA%20RESTful%20API%20Guide/paci-restful-api-guide-5.4.pdf


Accessing a Resource

A PACI resource is accessed by sending an HTTPS request to a PACI server. When the server receives a request, it processes it accordingly (performs actions or retrieves data) and sends back a response that can contain the data that you requested, an operation status code, or an error messate. All PACI resources are accessed at the following URL (referred to as baseURL) 

https://{ip_address | hostname}:port/paci/version

where:

  1. ip_address | hostname is the PACI server IP address or hostname.
  2. port is the port number on which the server is listening for REST requests
  3. paci must be typed exactly as shown
  4. version is the API version number

For our resource the baseURL will use the following: 

https://api.cloud.xmission.com:4464/paci/v1.0/


Server Management

Using this API can come in handy for various types of resource information for example you can use the API to list your current server, configure your server, even stop and start lets take a look at a few basic commands.

List your current servers

Use this request to obtain the list of servers owned by the current user 

GET https://api.cloud.xmission.com:4464/paci/v1.0/ve

A sample out put would list your current servers. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ve-list>
    <ve-info description="XMission minecraft server" state="STARTED" name="minecraft" subscription-id="1003209"/>
</ve-list>


More specific server info

If you want to be more specific and obtain information about a specific server you can add the server name like this: 

GET https://api.cloud.xmission.com:4464/paci/v1.0/ve/server1

A sample out put will look like this: 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ve>
    <id>296</id>
    <uuid>3c1c50b1.13d794f9065._7ff0</uuid>
    <hnId>14</hnId>
    <customer-id>1000001</customer-id>
    <name>server1</name>
    <description>Testing Server</description>
    <subscription-id>100001</subscription-id>
    <cpu number="4" power="1500"/>
    <ram-size>6400</ram-size>
    <bandwidth>10000</bandwidth>
    <ve-disk created="true" id="0" local="true" size="25"/>
    <platform>
        <template-info name="ubuntu-12.04-x86_64"/>
        <os-info type="ubuntu-12.04-x64" technology="CT"/>
    </platform>
    <network private-ip="10.0.0.0/8">
        <public-ip chunk-ref="1" id="269" address="123.123.123.123/24" gateway="123.123.123.1"/>
    </network>
    <state>STARTED</state>
    <primary-disk-id>0</primary-disk-id>
    <template-id>12</template-id>
    <admin login="root" password="[hidden]"/>
    <steady-state>STARTED</steady-state>
</ve>

Here you can see it shows you all relative information about the server including the number of CPUs, CPU Power, Ram, IP address and much more.

Many more useful command can be used as well - more common would be to start or stop your server.


Start / Stop your Server

PUT https://api.cloud.xmission.com:4464/paci/v1.0/ve/server1/stop

A sample output would be: 

VE START initiated

There is so much more you can do with this API including adjusting your server at peak times to compensate for your server load, and then readjusting them back during non peak times.

We have a great blog post regarding this API located on Transmission XMission's Company Journal

Use the Cloud Infrastructure API to Automatically Resize Your Server

This documentation is to be used as a guide. Your server will require different settings to optimize your traffic and this code is not perfect. We encourage you to customize it to fit your needs, or write it in a language of your choice. Remember to refer to the documentation.

Retrieved from "http://wiki.xmission.com/index.php?title=Advanced_Cloud_Hosting/Cloud_API&oldid=9304"