| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta name="Content-Type" content="text/html; charset=utf-8" /> |
| <title>Deltacloud Client Library</title> |
| <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" /> |
| <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" /> |
| |
| <script type="text/javascript" charset="utf-8"> |
| relpath = ''; |
| if (relpath != '') relpath += '/'; |
| </script> |
| <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script> |
| <script type="text/javascript" charset="utf-8" src="js/app.js"></script> |
| |
| </head> |
| <body> |
| <script type="text/javascript" charset="utf-8"> |
| if (window.top.frames.main) document.body.className = 'frames'; |
| </script> |
| |
| <div id="header"> |
| <div id="menu"> |
| |
| <a href="_index.html" title="Index">Index</a> » |
| <span class="title">File: README</span> |
| |
| |
| <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div> |
| </div> |
| |
| <div id="search"> |
| <a id="class_list_link" href="#">Class List</a> |
| <a id="method_list_link" href="#">Method List</a> |
| <a id ="file_list_link" href="#">File List</a> |
| </div> |
| |
| <div class="clear"></div> |
| </div> |
| |
| <iframe id="search_frame"></iframe> |
| |
| <div id="content"><div id='filecontents'><h1 id='deltacloud_client_ruby'>Deltacloud Client (Ruby)</h1> |
| |
| <p>The Deltacloud project includes a Ruby client. Other language-bindings are possible and will be supported soon. The client aims to insulate users from having to deal with HTTP and REST directly.</p> |
| |
| <p>Each resource type has an associated model to ease usage. Where resource reference other resources, natural navigation across the object model is possible.</p> |
| |
| <p>For example</p> |
| |
| <pre class="code"><span class='puts identifier id'>puts</span> <span class='instance identifier id'>instance</span><span class='dot token'>.</span><span class='image identifier id'>image</span><span class='dot token'>.</span><span class='name identifier id'>name</span> |
| <span class='puts identifier id'>puts</span> <span class='instance identifier id'>instance</span><span class='dot token'>.</span><span class='hardware_profile identifier id'>hardware_profile</span><span class='dot token'>.</span><span class='architecture identifier id'>architecture</span> |
| </pre> |
| |
| <h2 id='basics'>Basics</h2> |
| |
| <p>To use the client, you must require <code>deltacloud</code>.</p> |
| |
| <pre class="code"><span class='require identifier id'>require</span> <span class='string val'>'deltacloud'</span> |
| </pre> |
| |
| <h2 id='connecting_to_a_deltacloud_provider'>Connecting to a Deltacloud provider</h2> |
| |
| <pre class="code"><span class='require identifier id'>require</span> <span class='string val'>'deltacloud'</span> |
| |
| <span class='api_url identifier id'>api_url</span> <span class='assign token'>=</span> <span class='string val'>'http://localhost:3001/api'</span> |
| <span class='api_name identifier id'>api_name</span> <span class='assign token'>=</span> <span class='string val'>'mockuser'</span> |
| <span class='api_password identifier id'>api_password</span> <span class='assign token'>=</span> <span class='string val'>'mockpassword'</span> |
| |
| <span class='client identifier id'>client</span> <span class='assign token'>=</span> <span class='DeltaCloud constant id'>DeltaCloud</span><span class='dot token'>.</span><span class='new identifier id'>new</span><span class='lparen token'>(</span> <span class='api_name identifier id'>api_name</span><span class='comma token'>,</span> <span class='api_password identifier id'>api_password</span><span class='comma token'>,</span> <span class='api_url identifier id'>api_url</span> <span class='rparen token'>)</span> |
| |
| <span class='comment val'># work with client here</span> |
| </pre> |
| |
| <p>In addition to creating a client, operations may occur within a block included on the initialization</p> |
| |
| <pre class="code"><span class='DeltaCloud constant id'>DeltaCloud</span><span class='dot token'>.</span><span class='new identifier id'>new</span><span class='lparen token'>(</span> <span class='api_name identifier id'>api_name</span><span class='comma token'>,</span> <span class='api_password identifier id'>api_password</span><span class='comma token'>,</span> <span class='api_url identifier id'>api_url</span> <span class='rparen token'>)</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='client identifier id'>client</span><span class='bitor op'>|</span> |
| <span class='comment val'># work with client here</span> |
| <span class='end end kw'>end</span> |
| </pre> |
| |
| <p>In the event of a failure, any underlying HTTP transport exceptions will be thrown all the way out to the caller.</p> |
| |
| <h2 id='listing_realms'>Listing realms</h2> |
| |
| <p>You may retrieve a complete list of realms available to you</p> |
| |
| <pre class="code"><span class='realms identifier id'>realms</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='realms identifier id'>realms</span> |
| </pre> |
| |
| <p>You may retrieve a specific realm by its identifier</p> |
| |
| <pre class="code"><span class='realm identifier id'>realm</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='realm identifier id'>realm</span><span class='lparen token'>(</span> <span class='string val'>'us'</span> <span class='rparen token'>)</span> |
| </pre> |
| |
| <h2 id='listing_hardware_profiles'>Listing hardware profiles</h2> |
| |
| <p>You may retrieve a complete list of hardware profiles available for launching machines</p> |
| |
| <pre class="code"><span class='hwp identifier id'>hwp</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='hardware_profiles identifier id'>hardware_profiles</span> |
| </pre> |
| |
| <p>You may filter hardware profiles by architecture</p> |
| |
| <pre class="code"><span class='flavors identifier id'>flavors</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='hardware_profiles identifier id'>hardware_profiles</span><span class='lparen token'>(</span> <span class='symbol val'>:architecture=</span><span class='gt op'>></span><span class='string val'>'x86_64'</span> <span class='rparen token'>)</span> |
| </pre> |
| |
| <p>You may retrieve a specific hardware profile by its identifier</p> |
| |
| <pre class="code"><span class='flavor identifier id'>flavor</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='hardware_profile identifier id'>hardware_profile</span><span class='lparen token'>(</span> <span class='string val'>'m1-small'</span> <span class='rparen token'>)</span> |
| </pre> |
| |
| <h2 id='listing_images'>Listing images</h2> |
| |
| <p>You may retrieve a complete list of images</p> |
| |
| <pre class="code"><span class='images identifier id'>images</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='images identifier id'>images</span> |
| </pre> |
| |
| <p>You may retrieve a list of images owned by the currently authenticated user</p> |
| |
| <pre class="code"><span class='images identifier id'>images</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='images identifier id'>images</span><span class='lparen token'>(</span> <span class='symbol val'>:owner_id=</span><span class='gt op'>></span><span class='symbol val'>:self</span> <span class='rparen token'>)</span> |
| </pre> |
| |
| <p>You may retrieve a list of images visible to you but owned by a specific user</p> |
| |
| <pre class="code"><span class='images identifier id'>images</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='images identifier id'>images</span><span class='lparen token'>(</span> <span class='symbol val'>:owner_id=</span><span class='gt op'>></span><span class='string val'>'daryll'</span> <span class='rparen token'>)</span> |
| </pre> |
| |
| <p>You may retrieve a specific image by its identifier</p> |
| |
| <pre class="code"><span class='image identifier id'>image</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='image identifier id'>image</span><span class='lparen token'>(</span> <span class='string val'>'ami-8675309'</span> <span class='rparen token'>)</span> |
| </pre> |
| |
| <h2 id='listing_instances'>Listing instances</h2> |
| |
| <p>You may retrieve a list of all instances visible to you</p> |
| |
| <pre class="code"><span class='instances identifier id'>instances</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='instances identifier id'>instances</span> |
| </pre> |
| |
| <p>You may retrieve a specific instance by its identifier</p> |
| |
| <pre class="code"><span class='instance identifier id'>instance</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='instance identifier id'>instance</span><span class='lparen token'>(</span> <span class='string val'>'i-90125'</span> <span class='rparen token'>)</span> |
| </pre> |
| |
| <h2 id='launching_instances'>Launching instances</h2> |
| |
| <p>An instance may be launched using just an image identifier</p> |
| |
| <pre class="code"><span class='image identifier id'>image</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='image identifier id'>image</span><span class='lparen token'>(</span> <span class='string val'>'ami-8675309'</span> <span class='rparen token'>)</span> |
| <span class='instance identifier id'>instance</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='create_instance identifier id'>create_instance</span><span class='lparen token'>(</span> <span class='image identifier id'>image</span><span class='dot token'>.</span><span class='id identifier id'>id</span> <span class='rparen token'>)</span> |
| </pre> |
| |
| <p>Optionally, a flavor or realm may be specified</p> |
| |
| <pre class="code"><span class='instance identifier id'>instance</span> <span class='assign token'>=</span> <span class='client identifier id'>client</span><span class='dot token'>.</span><span class='create_instance identifier id'>create_instance</span><span class='lparen token'>(</span> <span class='image identifier id'>image</span><span class='dot token'>.</span><span class='id identifier id'>id</span><span class='comma token'>,</span> <span class='symbol val'>:flavor=</span><span class='gt op'>></span><span class='string val'>'m1-small'</span><span class='comma token'>,</span> <span class='symbol val'>:realm=</span><span class='gt op'>></span><span class='string val'>'us'</span> <span class='rparen token'>)</span> |
| </pre> |
| |
| <h2 id='manipulating_instances'>Manipulating instances</h2> |
| |
| <p>Given an instance, depending on its state, various actions <em>may</em> be available.</p> |
| |
| <p>To determine what’s available, the <code>instance#actions</code> method may be used.</p> |
| |
| <pre class="code"><span class='instance identifier id'>instance</span><span class='dot token'>.</span><span class='actions identifier id'>actions</span> <span class='comment val'># [ 'reboot', 'stop' ]</span> |
| </pre> |
| |
| <p>For a valid action, the method matching the action with an exclamation point may be called.</p> |
| |
| <pre class="code"><span class='instance identifier id'>instance</span><span class='dot token'>.</span><span class='reboot! fid id'>reboot!</span> |
| </pre> |
| |
| <p>Upon invoking an action, the instance will refresh its contents, in case the state has changed. To determine later if the state has changed again, the instance must be refetched using the <code>client.instance(...)</code> method.</p></div></div> |
| |
| <div id="footer"> |
| Generated on Fri Jul 30 12:16:23 2010 by |
| <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool">yard</a> |
| 0.5.6 (ruby-1.8.7). |
| </div> |
| |
| </body> |
| </html> |
