You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by se...@apache.org on 2013/06/05 16:45:58 UTC
[2/3] git commit: updated refs/heads/ACS101 to 31b001f
added examples from master
Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/31b001f0
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/31b001f0
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/31b001f0
Branch: refs/heads/ACS101
Commit: 31b001f08e6243d8fd243be2d72bbfd8efd04edd
Parents: ae82e47
Author: Sebastien Goasguen <ru...@gmail.com>
Authored: Fri May 31 14:04:49 2013 -0400
Committer: Sebastien Goasguen <ru...@gmail.com>
Committed: Fri May 31 14:04:49 2013 -0400
----------------------------------------------------------------------
docs/acs101/en-US/boto.xml | 128 +++++++++++++++++++++++++++---
docs/acs101/en-US/cloudstackapi.xml | 89 ++++++++++++++++++---
docs/acs101/en-US/libcloud.xml | 61 ++++++++++++--
3 files changed, 249 insertions(+), 29 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack/blob/31b001f0/docs/acs101/en-US/boto.xml
----------------------------------------------------------------------
diff --git a/docs/acs101/en-US/boto.xml b/docs/acs101/en-US/boto.xml
index 71280fc..8d2be64 100644
--- a/docs/acs101/en-US/boto.xml
+++ b/docs/acs101/en-US/boto.xml
@@ -1,6 +1,6 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "ACS101.ent">
%BOOK_ENTITIES;
]>
@@ -11,9 +11,9 @@
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
-
+
http://www.apache.org/licenses/LICENSE-2.0
-
+
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -23,10 +23,118 @@
-->
<section id="boto">
- <title>Boto Python module</title>
- <para>DevCloud is the &PRODUCT; sandbox. It is provided as a Virtual Box appliance. It is meant to be used as a development environment to easily test new &PRODUCT; development. It has also been used for training and &PRODUCT; demos since it provides a <emphasis>Cloud in a box</emphasis>.</para>
- <note>
- <para>DevCloud is provided as a convenience by community members. It is not an official &PRODUCT; release artifact.</para>
- <para>The &PRODUCT; source code however, contains tools to build your own DevCloud.</para>
- </note>
-</section>
+ <title>Examples</title>
+ <para>There are many tools available to interface with a AWS compatible API. In this section we provide
+ a few examples that users of &PRODUCT; can build upon.</para>
+
+ <section id="aws-api-boto-examples">
+ <title>Boto Examples</title>
+ <para>Boto is one of them. It is a Python package available at https://github.com/boto/boto.
+ In this section we provide two examples of Python scripts that use Boto and have been tested with the
+ &PRODUCT; AWS API Interface.</para>
+ <para>First is an EC2 example. Replace the Access and Secret Keys with your own and
+ update the endpoint.</para>
+ <para>
+ <example>
+ <title>An EC2 Boto example</title>
+ <programlisting>#!/usr/bin/env python
+
+import sys
+import os
+import boto
+import boto.ec2
+
+region = boto.ec2.regioninfo.RegionInfo(name="ROOT",endpoint="localhost")
+apikey='GwNnpUPrO6KgIdZu01z_ZhhZnKjtSdRwuYd4DvpzvFpyxGMvrzno2q05MB0ViBoFYtdqKd'
+secretkey='t4eXLEYWw7chBhDlaKf38adCMSHx_wlds6JfSx3z9fSpSOm0AbP9Moj0oGIzy2LSC8iw'
+
+def main():
+ '''Establish connection to EC2 cloud'''
+ conn =boto.connect_ec2(aws_access_key_id=apikey,
+ aws_secret_access_key=secretkey,
+ is_secure=False,
+ region=region,
+ port=7080,
+ path="/awsapi",
+ api_version="2010-11-15")
+
+ '''Get list of images that I own'''
+ images = conn.get_all_images()
+ print images
+ myimage = images[0]
+ '''Pick an instance type'''
+ vm_type='m1.small'
+ reservation = myimage.run(instance_type=vm_type,security_groups=['default'])
+
+if __name__ == '__main__':
+ main()
+ </programlisting>
+ </example>
+ </para>
+ <para>Second is an S3 example. Replace the Access and Secret keys with your own,
+ as well as the endpoint of the service. Be sure to also update the file paths to something
+ that exists on your machine.</para>
+ <para>
+ <example>
+ <title>An S3 Boto Example</title>
+ <programlisting>#!/usr/bin/env python
+
+import sys
+import os
+from boto.s3.key import Key
+from boto.s3.connection import S3Connection
+from boto.s3.connection import OrdinaryCallingFormat
+
+apikey='ChOw-pwdcCFy6fpeyv6kUaR0NnhzmG3tE7HLN2z3OB_s-ogF5HjZtN4rnzKnq2UjtnHeg_yLA5gOw'
+secretkey='IMY8R7CJQiSGFk4cHwfXXN3DUFXz07cCiU80eM3MCmfLs7kusgyOfm0g9qzXRXhoAPCH-IRxXc3w'
+
+cf=OrdinaryCallingFormat()
+
+def main():
+ '''Establish connection to S3 service'''
+ conn =S3Connection(aws_access_key_id=apikey,aws_secret_access_key=secretkey, \
+ is_secure=False, \
+ host='localhost', \
+ port=7080, \
+ calling_format=cf, \
+ path="/awsapi/rest/AmazonS3")
+
+ try:
+ bucket=conn.create_bucket('cloudstack')
+ k = Key(bucket)
+ k.key = 'test'
+ try:
+ k.set_contents_from_filename('/Users/runseb/Desktop/s3cs.py')
+ except:
+ print 'could not write file'
+ pass
+ except:
+ bucket = conn.get_bucket('cloudstack')
+ k = Key(bucket)
+ k.key = 'test'
+ try:
+ k.get_contents_to_filename('/Users/runseb/Desktop/foobar')
+ except:
+ print 'Could not get file'
+ pass
+
+ try:
+ bucket1=conn.create_bucket('teststring')
+ k=Key(bucket1)
+ k.key('foobar')
+ k.set_contents_from_string('This is my silly test')
+ except:
+ bucket1=conn.get_bucket('teststring')
+ k = Key(bucket1)
+ k.key='foobar'
+ k.get_contents_as_string()
+
+if __name__ == '__main__':
+ main()
+
+ </programlisting>
+ </example>
+ </para>
+ </section>
+
+ </section>
http://git-wip-us.apache.org/repos/asf/cloudstack/blob/31b001f0/docs/acs101/en-US/cloudstackapi.xml
----------------------------------------------------------------------
diff --git a/docs/acs101/en-US/cloudstackapi.xml b/docs/acs101/en-US/cloudstackapi.xml
index e7ec6b2..6d6155c 100644
--- a/docs/acs101/en-US/cloudstackapi.xml
+++ b/docs/acs101/en-US/cloudstackapi.xml
@@ -1,6 +1,6 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "ACS101.ent">
%BOOK_ENTITIES;
]>
@@ -11,9 +11,9 @@
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
-
+
http://www.apache.org/licenses/LICENSE-2.0
-
+
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -23,10 +23,79 @@
-->
<section id="cloudstackapi">
- <title>The &PRODUCT; API</title>
- <para>DevCloud is the &PRODUCT; sandbox. It is provided as a Virtual Box appliance. It is meant to be used as a development environment to easily test new &PRODUCT; development. It has also been used for training and &PRODUCT; demos since it provides a <emphasis>Cloud in a box</emphasis>.</para>
- <note>
- <para>DevCloud is provided as a convenience by community members. It is not an official &PRODUCT; release artifact.</para>
- <para>The &PRODUCT; source code however, contains tools to build your own DevCloud.</para>
- </note>
-</section>
+ <title>How to sign an API call with Python</title>
+ <para>To illustrate the procedure used to sign API calls we present a step by step interactive session
+ using Python.</para>
+
+ <para>First import the required modules:</para>
+ <programlisting>
+
+ <![CDATA[
+$python
+Python 2.7.3 (default, Nov 17 2012, 19:54:34)
+[GCC 4.2.1 Compatible Apple Clang 4.1 ((tags/Apple/clang-421.11.66))] on darwin
+Type "help", "copyright", "credits" or "license" for more information.
+>>> import urllib2
+>>> import urllib
+>>> import hashlib
+>>> import hmac
+>>> import base64
+ ]]>
+ </programlisting>
+
+ <para>Define the endpoint of the Cloud, the command that you want to execute and the keys of the user.</para>
+ <programlisting>
+ <![CDATA[
+
+>>> baseurl='http://localhost:8080/client/api?'
+>>> request={}
+>>> request['command']='listUsers'
+>>> request['response']='json'
+>>> request['apikey']='plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg'
+>>> secretkey='VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ'
+ ]]>
+ </programlisting>
+ <para>Build the request string:</para>
+ <programlisting>
+ <![CDATA[
+>>> request_str='&'.join(['='.join([k,urllib.quote_plus(request[k])]) for k in request.keys()])
+>>> request_str
+'apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json'
+ ]]>
+ </programlisting>
+
+ <para>Compute the signature with hmac, do a 64 bit encoding and a url encoding: </para>
+ <programlisting>
+ <![CDATA[
+>>> sig_str='&'.join(['='.join([k.lower(),urllib.quote_plus(request[k].lower().replace('+','%20'))])for k in sorted(request.iterkeys())])
+>>> sig_str
+'apikey=plgwjfzk4gys3momtvmjuvg-x-jlwlnfauj9gabbbf9edm-kaymmailqzzq1elzlyq_u38zcm0bewzgudp66mg&command=listusers&response=json'
+>>> sig=hmac.new(secretkey,sig_str,hashlib.sha1)
+>>> sig
+<hmac.HMAC instance at 0x10d91d680>
+>>> sig=hmac.new(secretkey,sig_str,hashlib.sha1).digest()
+>>> sig
+'M:]\x0e\xaf\xfb\x8f\xf2y\xf1p\x91\x1e\x89\x8a\xa1\x05\xc4A\xdb'
+>>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest())
+>>> sig
+'TTpdDq/7j/J58XCRHomKoQXEQds=\n'
+>>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip()
+>>> sig
+'TTpdDq/7j/J58XCRHomKoQXEQds='
+>>> sig=urllib.quote_plus(base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip())
+ ]]>
+ </programlisting>
+
+ <para>Finally, build the entire string and do an http GET:</para>
+ <programlisting>
+ <![CDATA[
+>>> req=baseurl+request_str+'&signature='+sig
+>>> req
+'http://localhost:8080/client/api?apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json&signature=TTpdDq%2F7j%2FJ58XCRHomKoQXEQds%3D'
+>>> res=urllib2.urlopen(req)
+>>> res.read()
+'{ "listusersresponse" : { "count":3 ,"user" : [ {"id":"7ed6d5da-93b2-4545-a502-23d20b48ef2a","username":"admin","firstname":"admin","lastname":"cloud","created":"2012-07-05T12:18:27-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg","secretkey":"VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"1fea6418-5576-4989-a21e-4790787bbee3","username":"runseb","firstname":"foobar","lastname":"goa","email":"joe@smith.com","created":"2013-04-10T16:52:06-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"Xhsb3MewjJQaXXMszRcLvQI9_NPy_UcbDj1QXikkVbDC9MDSPwWdtZ1bUY1H7JBEYTtDDLY3yuchCeW778GkBA","secretkey":"gIsgmi8C5YwxMHjX5o51pSe0kqs6JnKriw0jJBLceY5b
gnfzKjL4aM6ctJX-i1ddQIHJLbLJDK9MRzsKk6xZ_w","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"52f65396-183c-4473-883f-a37e7bb93967","username":"toto","firstname":"john","lastname":"smith","email":"john@smith.com","created":"2013-04-23T04:27:22-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"THaA6fFWS_OmvU8od201omxFC8yKNL_Hc5ZCS77LFCJsRzSx48JyZucbUul6XYbEg-ZyXMl_wuEpECzK-wKnow","secretkey":"O5ywpqJorAsEBKR_5jEvrtGHfWL1Y_j1E4Z_iCr8OKCYcsPIOdVcfzjJQ8YqK0a5EzSpoRrjOFiLsG0hQrYnDA","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"} ] } }'
+ ]]>
+ </programlisting>
+
+ </section>
http://git-wip-us.apache.org/repos/asf/cloudstack/blob/31b001f0/docs/acs101/en-US/libcloud.xml
----------------------------------------------------------------------
diff --git a/docs/acs101/en-US/libcloud.xml b/docs/acs101/en-US/libcloud.xml
index 6794864..3c98e06 100644
--- a/docs/acs101/en-US/libcloud.xml
+++ b/docs/acs101/en-US/libcloud.xml
@@ -1,6 +1,6 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "ACS101.ent">
%BOOK_ENTITIES;
]>
@@ -11,9 +11,9 @@
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
-
+
http://www.apache.org/licenses/LICENSE-2.0
-
+
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -24,9 +24,52 @@
<section id="libcloud">
<title>Apache Libcloud</title>
- <para>DevCloud is the &PRODUCT; sandbox. It is provided as a Virtual Box appliance. It is meant to be used as a development environment to easily test new &PRODUCT; development. It has also been used for training and &PRODUCT; demos since it provides a <emphasis>Cloud in a box</emphasis>.</para>
- <note>
- <para>DevCloud is provided as a convenience by community members. It is not an official &PRODUCT; release artifact.</para>
- <para>The &PRODUCT; source code however, contains tools to build your own DevCloud.</para>
- </note>
-</section>
+ <para>There are many tools available to interface with the &PRODUCT; API. Apache Libcloud is one of those. In this section
+ we provide a basic example of how to use Libcloud with &PRODUCT;. It assumes that you have access to a &PRODUCT; endpoint and that you have the API access key and secret key of a user.</para>
+ <para>To install Libcloud refer to the libcloud website. If you are familiar with Pypi simply do:</para>
+ <programlisting>pip install apache-libcloud</programlisting>
+ <para>You should see the following output:</para>
+ <programlisting>
+pip install apache-libcloud
+Downloading/unpacking apache-libcloud
+ Downloading apache-libcloud-0.12.4.tar.bz2 (376kB): 376kB downloaded
+ Running setup.py egg_info for package apache-libcloud
+
+Installing collected packages: apache-libcloud
+ Running setup.py install for apache-libcloud
+
+Successfully installed apache-libcloud
+Cleaning up...
+ </programlisting>
+
+ <para>You can then open a Python interactive shell, create an instance of a &PRODUCT; driver and call the available methods via the libcloud API.</para>
+
+ <programlisting>
+ <![CDATA[
+>>> from libcloud.compute.types import Provider
+>>> from libcloud.compute.providers import get_driver
+>>> Driver = get_driver(Provider.CLOUDSTACK)
+>>> apikey='plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg'
+>>> secretkey='VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ'
+>>> host='http://localhost:8080'
+>>> path='/client/api'
+>>> conn=Driver(apikey,secretkey,secure='False',host='localhost:8080',path=path)
+>>> conn=Driver(key=apikey,secret=secretkey,secure=False,host='localhost',port='8080',path=path)
+>>> conn.list_images()
+[<NodeImage: id=13ccff62-132b-4caf-b456-e8ef20cbff0e, name=tiny Linux, driver=CloudStack ...>]
+>>> conn.list_sizes()
+[<NodeSize: id=ef2537ad-c70f-11e1-821b-0800277e749c, name=tinyOffering, ram=100 disk=0 bandwidth=0 price=0 driver=CloudStack ...>, <NodeSize: id=c66c2557-12a7-4b32-94f4-48837da3fa84, name=Small Instance, ram=512 disk=0 bandwidth=0 price=0 driver=CloudStack ...>, <NodeSize: id=3d8b82e5-d8e7-48d5-a554-cf853111bc50, name=Medium Instance, ram=1024 disk=0 bandwidth=0 price=0 driver=CloudStack ...>]
+>>> images=conn.list_images()
+>>> offerings=conn.list_sizes()
+>>> node=conn.create_node(name='toto',image=images[0],size=offerings[0])
+>>> help(node)
+>>> node.get_uuid()
+'b1aa381ba1de7f2d5048e248848993d5a900984f'
+>>> node.name
+u'toto'
+]]>
+ </programlisting>
+
+ <para>One of the interesting use cases of Libcloud is that you can use multiple Cloud Providers, such as AWS, Rackspace, OpenNebula, vCloud and so on. You can then create Driver instances to each of these clouds and create your own multi cloud application.</para>
+
+ </section>