You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@libcloud.apache.org by to...@apache.org on 2013/08/03 23:33:28 UTC
[1/5] git commit: Update documentation index page.
Updated Branches:
refs/heads/trunk 73bd38289 -> 6ed10daab
Update documentation index page.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/7cef706b
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/7cef706b
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/7cef706b
Branch: refs/heads/trunk
Commit: 7cef706b034cde96a1a6b562d564ef0f4b773453
Parents: 73bd382
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 19:03:18 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 19:03:18 2013 +0200
----------------------------------------------------------------------
docs/index.rst | 12 +++++++-----
1 file changed, 7 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/7cef706b/docs/index.rst
----------------------------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index be5f382..8ee7bbe 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,13 +12,15 @@ Welcome to Apache Libcloud's documentation!
Unless noted otherwise, all of the examples in the documentation are
licensed under the `Apache 2.0 license`_.
-Apache Libcloud is a Python library which abstracts away the differences
-between multiple cloud providers. It current can manage four different cloud
-resources:
+Apache Libcloud is a Python library which hides differences between different
+cloud provider APIs and allows you to manage different cloud resources through
+a unified and easy to use API.
-* :doc:`Cloud servers </compute/index>` - services such as Amazon EC2 and
+Resource you can manage with Libcloud are divided in the following categories:
+
+* :doc:`Cloud Servers </compute/index>` - services such as Amazon EC2 and
RackSpace CloudServers
-* :doc:`Cloud object storage </storage/index>` - services such as Amazon S3 and
+* :doc:`Cloud Object Storage </storage/index>` - services such as Amazon S3 and
Rackspace CloudFiles
* :doc:`Load Balancers as a Service </loadbalancer/index>`
* :doc:`DNS as a Service </dns/index>`
[4/5] git commit: docs: Port more docs over.
Posted by to...@apache.org.
docs: Port more docs over.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/04a06cd4
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/04a06cd4
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/04a06cd4
Branch: refs/heads/trunk
Commit: 04a06cd4ac3f9933fb2c2acd1875487a88957e07
Parents: acfceb4
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 23:23:48 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 23:23:48 2013 +0200
----------------------------------------------------------------------
docs/dns/index.rst | 11 +++++++++--
docs/loadbalancer/index.rst | 12 ++++++++++--
docs/storage/index.rst | 13 +++++++++++--
3 files changed, 30 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/04a06cd4/docs/dns/index.rst
----------------------------------------------------------------------
diff --git a/docs/dns/index.rst b/docs/dns/index.rst
index dafb455..e0fe0f6 100644
--- a/docs/dns/index.rst
+++ b/docs/dns/index.rst
@@ -1,9 +1,16 @@
DNS
===
-.. note::
+DNS API allows you to manage DNS as A Service and services such as Zerigo DNS,
+Rackspace Cloud DNS and others.
- TODO: Write me!
+Terminology
+-----------
+
+* **Zone** - represents a DNS zone or so called domain.
+* **Record** - represents a DNS record. Each record belongs to a Zone and has
+ a record type and data attribute. Data depends on the record type.
+* **RecordType** - represents a DNS record type (A, AAAA, MX, TXT, etc.)
Examples
--------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/04a06cd4/docs/loadbalancer/index.rst
----------------------------------------------------------------------
diff --git a/docs/loadbalancer/index.rst b/docs/loadbalancer/index.rst
index 59f17c2..77accae 100644
--- a/docs/loadbalancer/index.rst
+++ b/docs/loadbalancer/index.rst
@@ -1,9 +1,17 @@
Load Balancers
==============
-.. note::
+Load Balancer API allows you to manage Load Balancers as a service and services
+such as Rackspace Cloud Load Balancers, GoGrid Load Balancers and Ninefold Load
+Balancers.
- TODO: Write me!
+Terminology
+-----------
+
+* **LoadBalancer** - represents a load balancer instance.
+* **Member** - represents a load balancer member.
+* **Algorithm** - represents a load balancing algorithm (round-robin, random,
+ least connections, etc.).
Examples
--------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/04a06cd4/docs/storage/index.rst
----------------------------------------------------------------------
diff --git a/docs/storage/index.rst b/docs/storage/index.rst
index 6d93f9e..4b06f7c 100644
--- a/docs/storage/index.rst
+++ b/docs/storage/index.rst
@@ -1,9 +1,18 @@
Object Storage
==============
-.. note::
+Storage API allows you to manage cloud object storage (not to be confused with
+cloud block storage) and services such as Amazon S3, Rackspace CloudFiles,
+Google Storage and others.
- TODO: Write me!
+Terminology
+-----------
+
+* **Object** - represents an object or so called BLOB.
+* **Container** - represents a container which can contain multiple objects.
+ You can think of it as a folder on a file system. Difference between
+ container and a folder on file system is that containers cannot be nested.
+ Some APIs and providers (e.g. AWS) refer to it as a Bucket.
Examples
--------
[5/5] git commit: docs: Add info about block storage methods to the
compute section.
Posted by to...@apache.org.
docs: Add info about block storage methods to the compute section.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/6ed10daa
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/6ed10daa
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/6ed10daa
Branch: refs/heads/trunk
Commit: 6ed10daabe4967bacd3a8b228e9849b36c41ae2f
Parents: 04a06cd
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 23:32:56 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 23:32:56 2013 +0200
----------------------------------------------------------------------
docs/compute/api.rst | 3 +++
docs/compute/index.rst | 15 +++++++++++++++
docs/index.rst | 2 +-
3 files changed, 19 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/6ed10daa/docs/compute/api.rst
----------------------------------------------------------------------
diff --git a/docs/compute/api.rst b/docs/compute/api.rst
index 13d9a1f..ec93283 100644
--- a/docs/compute/api.rst
+++ b/docs/compute/api.rst
@@ -3,3 +3,6 @@ Compute Base API
.. autoclass:: libcloud.compute.base.NodeDriver
:members:
+
+.. autoclass:: libcloud.compute.base.StorageVolume
+ :members:
http://git-wip-us.apache.org/repos/asf/libcloud/blob/6ed10daa/docs/compute/index.rst
----------------------------------------------------------------------
diff --git a/docs/compute/index.rst b/docs/compute/index.rst
index af0dbb8..ca8c909 100644
--- a/docs/compute/index.rst
+++ b/docs/compute/index.rst
@@ -10,9 +10,18 @@ allow you to execute arbitrary shell commands. This functionality is usually
used to prepare your freshly created server, install your SSH key, and run a
configuration management tool (such as Puppet, Chef, or cfengine) on it.
+Besides managing cloud and virtual servers, compute components allso allows you
+to manage cloud block storage (not to be confused with cloud object storage)
+for providers which support it.
+Block storage management is lives under compute API, because it is in most cases
+tightly coupled with compute resources.
+
Terminology
-----------
+Compute
+~~~~~~~
+
* **Node** - represents a cloud or virtual server.
* **NodeSize** - represents node hardware configuration. Usually this is amount
of the available RAM, bandwidth, CPU speed and disk size. Most of the drivers
@@ -22,6 +31,12 @@ Terminology
* **NodeState** - represents a node state. Standard states are: ``running``,
``rebooting``, ``terminated``, ``pending``, and ``unknown``.
+Block Storage
+~~~~~~~~~~~~~
+
+* **StorageVolume** - represents a block storage volume
+* **VolumeSnapshot** - represents a point in time snapshot of a StorageVolume
+
Examples
--------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/6ed10daa/docs/index.rst
----------------------------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index 9305655..984a5b2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -32,7 +32,7 @@ Resource you can manage with Libcloud are divided in the following categories:
.. toctree::
:glob:
- :maxdepth: 2
+ :maxdepth: 3
:hidden:
compute/*
[3/5] git commit: docs: Add getting started page, update index page.
Posted by to...@apache.org.
docs: Add getting started page, update index page.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/acfceb4e
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/acfceb4e
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/acfceb4e
Branch: refs/heads/trunk
Commit: acfceb4e93cb268a92ddad79ed886106f4635080
Parents: 2dbcc74
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 23:16:30 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 23:16:30 2013 +0200
----------------------------------------------------------------------
docs/_static/images/libcloud_logo.png | Bin 0 -> 9716 bytes
docs/_static/images/supported_providers.png | Bin 0 -> 110558 bytes
docs/conf.py | 2 +-
.../compute/bootstrapping_puppet_on_node.py | 30 +++++++++++++
docs/examples/compute/create_node.py | 19 ++++++++
docs/examples/compute/list_nodes.py | 11 +++++
.../list_nodes_across_multiple_providers.py | 26 +++++++++++
docs/getting-started.rst | 44 +++++++++++++++++++
docs/index.rst | 5 +++
9 files changed, 136 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/acfceb4e/docs/_static/images/libcloud_logo.png
----------------------------------------------------------------------
diff --git a/docs/_static/images/libcloud_logo.png b/docs/_static/images/libcloud_logo.png
new file mode 100755
index 0000000..f583f93
Binary files /dev/null and b/docs/_static/images/libcloud_logo.png differ
http://git-wip-us.apache.org/repos/asf/libcloud/blob/acfceb4e/docs/_static/images/supported_providers.png
----------------------------------------------------------------------
diff --git a/docs/_static/images/supported_providers.png b/docs/_static/images/supported_providers.png
new file mode 100644
index 0000000..27645f6
Binary files /dev/null and b/docs/_static/images/supported_providers.png differ
http://git-wip-us.apache.org/repos/asf/libcloud/blob/acfceb4e/docs/conf.py
----------------------------------------------------------------------
diff --git a/docs/conf.py b/docs/conf.py
index 66355a5..5383442 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -125,7 +125,7 @@ else:
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static', '_static/images/']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
http://git-wip-us.apache.org/repos/asf/libcloud/blob/acfceb4e/docs/examples/compute/bootstrapping_puppet_on_node.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/bootstrapping_puppet_on_node.py b/docs/examples/compute/bootstrapping_puppet_on_node.py
new file mode 100644
index 0000000..c72921f
--- /dev/null
+++ b/docs/examples/compute/bootstrapping_puppet_on_node.py
@@ -0,0 +1,30 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+from libcloud.compute.deployment import MultiStepDeployment
+from libcloud.compute.deployment import ScriptDeployment, SSHKeyDeployment
+import os
+
+RACKSPACE_USER = 'your username'
+RACKSPACE_KEY = 'your key'
+
+Driver = get_driver(Provider.RACKSPACE)
+conn = Driver(RACKSPACE_USER, RACKSPACE_KEY)
+
+# read your public key in
+# Note: This key will be added to the authorized keys for the root user
+# (/root/.ssh/authorized_keys)
+sd = SSHKeyDeployment(open(os.path.expanduser("~/.ssh/id_rsa.pub")).read())
+# a simple script to install puppet post boot, can be much more complicated.
+script = ScriptDeployment("apt-get -y install puppet")
+# a task that first installs the ssh key, and then runs the script
+msd = MultiStepDeployment([sd, script])
+
+images = conn.list_images()
+sizes = conn.list_sizes()
+
+# deploy_node takes the same base keyword arguments as create_node.
+node = conn.deploy_node(name='test', image=images[0], size=sizes[0],
+ deploy=msd)
+# <Node: uuid=..., name=test, state=3, public_ip=['1.1.1.1'],
+# provider=Rackspace ...>
+# the node is now booted, with your ssh key and puppet installed.
http://git-wip-us.apache.org/repos/asf/libcloud/blob/acfceb4e/docs/examples/compute/create_node.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/create_node.py b/docs/examples/compute/create_node.py
new file mode 100644
index 0000000..9a645c8
--- /dev/null
+++ b/docs/examples/compute/create_node.py
@@ -0,0 +1,19 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+RACKSPACE_USER = 'your username'
+RACKSPACE_KEY = 'your key'
+
+Driver = get_driver(Provider.RACKSPACE)
+conn = Driver(RACKSPACE_USER, RACKSPACE_KEY)
+
+# retrieve available images and sizes
+images = conn.list_images()
+# [<NodeImage: id=3, name=Gentoo 2008.0, driver=Rackspace ...>, ...]
+sizes = conn.list_sizes()
+# [<NodeSize: id=1, name=256 server, ram=256 ... driver=Rackspace ...>, ...]
+
+# create node with first image and first size
+node = conn.create_node(name='test', image=images[0], size=sizes[0])
+# <Node: uuid=..., name=test, state=3, public_ip=['1.1.1.1'],
+# provider=Rackspace ...>
http://git-wip-us.apache.org/repos/asf/libcloud/blob/acfceb4e/docs/examples/compute/list_nodes.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/list_nodes.py b/docs/examples/compute/list_nodes.py
new file mode 100644
index 0000000..97afdcf
--- /dev/null
+++ b/docs/examples/compute/list_nodes.py
@@ -0,0 +1,11 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+EC2_ACCESS_ID = 'your access id'
+EC2_SECRET_KEY = 'your secret key'
+
+Driver = get_driver(Provider.EC2)
+conn = Driver(EC2_ACCESS_ID, EC2_SECRET_KEY)
+
+nodes = conn.list_nodes()
+# [<Node: uuid=..., state=3, public_ip=['1.1.1.1'], provider=EC2 ...>, ...]
http://git-wip-us.apache.org/repos/asf/libcloud/blob/acfceb4e/docs/examples/compute/list_nodes_across_multiple_providers.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/list_nodes_across_multiple_providers.py b/docs/examples/compute/list_nodes_across_multiple_providers.py
new file mode 100644
index 0000000..d3d19fc
--- /dev/null
+++ b/docs/examples/compute/list_nodes_across_multiple_providers.py
@@ -0,0 +1,26 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+EC2_ACCESS_ID = 'your access id'
+EC2_SECRET_KEY = 'your secret key'
+SLICEHOST_API_KEY = 'your api key'
+RACKSPACE_USER = 'your username'
+RACKSPACE_KEY = 'your key'
+
+EC2Driver = get_driver(Provider.EC2)
+SlicehostDriver = get_driver(Provider.SLICEHOST)
+RackspaceDriver = get_driver(Provider.RACKSPACE)
+
+drivers = [EC2Driver(EC2_ACCESS_ID, EC2_SECRET_KEY),
+ SlicehostDriver(SLICEHOST_API_KEY),
+ RackspaceDriver(RACKSPACE_USER, RACKSPACE_KEY)]
+
+nodes = []
+for driver in drivers:
+ nodes += driver.list_nodes()
+print nodes
+# [ <Node: provider=Amazon, status=RUNNING, name=bob, ip=1.2.3.4.5>,
+# <Node: provider=Slicehost, status=REBOOT, name=korine, ip=6.7.8.9>, ... ]
+
+# Reboot all nodes named 'test'
+[node.reboot() for node in nodes if node.name == 'test']
http://git-wip-us.apache.org/repos/asf/libcloud/blob/acfceb4e/docs/getting-started.rst
----------------------------------------------------------------------
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
new file mode 100644
index 0000000..7352480
--- /dev/null
+++ b/docs/getting-started.rst
@@ -0,0 +1,44 @@
+Getting Started
+===============
+
+Installation
+------------
+
+Libcloud is available on PyPi and can be installed using pip:
+
+.. sourcecode:: bash
+
+ pip install apache-libcloud
+
+Upgrading
+---------
+
+If you used pip to install the library you can also use it to upgrade it:
+
+.. sourcecode:: bash
+
+ pip install --upgrade apache-libcloud
+
+Example: Connecting with a Driver
+---------------------------------
+
+.. literalinclude:: /examples/compute/list_nodes.py
+ :language: python
+
+Example: Creating a Node
+------------------------
+
+.. literalinclude:: /examples/compute/create_node.py
+ :language: python
+
+Example: List Nodes Across Multiple Providers
+---------------------------------------------
+
+.. literalinclude:: /examples/compute/list_nodes_across_multiple_providers.py
+ :language: python
+
+Example: Bootstrapping Puppet on a Node
+---------------------------------------
+
+.. literalinclude:: /examples/compute/bootstrapping_puppet_on_node.py
+ :language: python
http://git-wip-us.apache.org/repos/asf/libcloud/blob/acfceb4e/docs/index.rst
----------------------------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index 8ee7bbe..9305655 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -25,6 +25,11 @@ Resource you can manage with Libcloud are divided in the following categories:
* :doc:`Load Balancers as a Service </loadbalancer/index>`
* :doc:`DNS as a Service </dns/index>`
+.. figure:: /_static/images/supported_providers.png
+ :align: center
+
+ A subset of supported providers in Libcloud.
+
.. toctree::
:glob:
:maxdepth: 2
[2/5] git commit: Use nature Sphinx theme when not on RTD.
Posted by to...@apache.org.
Use nature Sphinx theme when not on RTD.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/2dbcc74d
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/2dbcc74d
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/2dbcc74d
Branch: refs/heads/trunk
Commit: 2dbcc74d14cb7e7c4ff75b229d23b95805838fb7
Parents: 7cef706
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 21:04:40 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 21:04:40 2013 +0200
----------------------------------------------------------------------
docs/conf.py | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/2dbcc74d/docs/conf.py
----------------------------------------------------------------------
diff --git a/docs/conf.py b/docs/conf.py
index 3b03a61..66355a5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -91,7 +91,12 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'default'
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if on_rtd:
+ html_theme = 'default'
+else:
+ html_theme = 'nature'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the