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/10/11 15:24:27 UTC
[1/3] git commit: docs: Add more OpenStack driver docs.
Updated Branches:
refs/heads/trunk 0530b792d -> 8a4c4a80f
docs: Add more OpenStack driver docs.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/f7c81f65
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/f7c81f65
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/f7c81f65
Branch: refs/heads/trunk
Commit: f7c81f65a5d6d7050d8b9908a7a38c1e3462ef01
Parents: 0530b79
Author: Tomaz Muraus <to...@apache.org>
Authored: Fri Oct 11 15:06:14 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Fri Oct 11 15:06:14 2013 +0200
----------------------------------------------------------------------
docs/compute/drivers/openstack.rst | 85 ++++++++++++++------
.../custom_service_catalog_selection_args.py | 18 +++++
.../compute/openstack/force_auth_token.py | 16 ++++
.../compute/openstack/force_base_url.py | 16 ++++
docs/examples/compute/openstack/simple_auth.py | 15 ++++
5 files changed, 127 insertions(+), 23 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/f7c81f65/docs/compute/drivers/openstack.rst
----------------------------------------------------------------------
diff --git a/docs/compute/drivers/openstack.rst b/docs/compute/drivers/openstack.rst
index 0492bb4..2566a65 100644
--- a/docs/compute/drivers/openstack.rst
+++ b/docs/compute/drivers/openstack.rst
@@ -4,15 +4,16 @@ OpenStack Compute Driver Documentation
Connecting to the OpenStack installation
----------------------------------------
-OpenStack driver constructor takes different arguments with which you tell it
-information about your OpenStack installation. Those arguments describe things
-such as the authentication service API URL, authentication service API version
-and so on.
+OpenStack driver constructor takes different arguments with which you describe
+your OpenStack installation. Those arguments describe things such as the
+authentication service API URL, authentication service API version and so on.
-Keep in mind that majority of those arguments are optional and in the most
+Keep in mind that the majority of those arguments are optional and in the most
common scenario with a default installation, you will only need to provide
``ex_force_auth_url`` argument.
+Available arguments:
+
* ``ex_force_auth_url`` - Authentication service (Keystone) API URL (e.g.
``http://192.168.1.101:5000/v2.0``)
* ``ex_force_auth_version`` - API version of the authentication service. This
@@ -40,31 +41,73 @@ common scenario with a default installation, you will only need to provide
* ``ex_force_service_type``
* ``ex_force_service_name``
* ``ex_force_service_region``
-* ``ex_force_base_url``
+* ``ex_force_base_url`` - Base URL to the OpenStack API endpoint. By default,
+ driver obtains API endpoint URL from the server catalog, but if this argument
+ is provided, this step is skipped and the provided value is used directly.
+
+Some examples which show how to use this arguments can be found in the section
+bellow.
Examples
+--------
-1. Most common use case - specifying only authentication service endpoint URL
- and API version
+1. Most common use case - specifying only authentication service endpoint URL and API version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-2. Specifying which entry to select in the service catalog using service_type,
- service_name and service_region arguments
+.. literalinclude:: /examples/compute/openstack/simple_auth.py
+ :language: python
-3. Skipping the endpoint selection using service catalog by providing
- ``ex_force_base_url`` argument
+2. Specifying which entry to select in the service catalog using service_type service_name and service_region arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-4. Skipping normal authentication flow and hitting the API endpoint directly
- using the ``ex_force_auth_token`` argument
+.. literalinclude:: /examples/compute/openstack/custom_service_catalog_selection_args.py
+ :language: python
+3. Skipping the endpoint selection using service catalog by providing ``ex_force_base_url`` argument
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Simple workflow
----------------
+.. literalinclude:: /examples/compute/openstack/force_base_url.py
+ :language: python
+
+4. Skipping normal authentication flow and hitting the API endpoint directly using the ``ex_force_auth_token`` argument
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: /examples/compute/openstack/force_auth_token.py
+ :language: python
+
+Non-standard functionality and extension methods
+------------------------------------------------
+
+OpenStack driver exposes a bunch of non-standard functionality through
+extension methods and arguments.
+
+This functionality includes:
+
+* server image management
+* network management
+* floating IP management
+* key-pair management
+
+For information on how to use this functionality please see the method
+docstrings bellow.
+
+Other Information
+----------------
+
+Authentication token re-use
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since version 0.13.0, the driver caches auth token in memory and re-uses it
+between different requests.
+
+This means that driver will only hit authentication service and obtain auth
+token on the first request or if the auth token is about to expire.
Troubleshooting
---------------
I get ``Could not find specified endpoint`` error
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This error indicates that the driver couldn't find a specified API endpoint
in the service catalog returned by the authentication service.
@@ -92,12 +135,8 @@ If the service catalog is empty, you have two options:
2. Provide the API endpoint url using ``ex_force_base_url`` argument and skip
the "endpoint selection using the service catalog" step all together
-TODO: link to the ml thread
-
I get ``Resource not found`` error
-----------------------------------
-
-TODO: link to the ml thread
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This error most likely indicates that you have used an invalid value for the
``ex_force_base_url`` argument.
@@ -109,6 +148,6 @@ service are two different services which listen on different ports.
API Docs
--------
-.. autoclass:: libcloud.compute.drivers.openstack.OpenStackNodeDriver
+.. autoclass:: libcloud.compute.drivers.openstack.OpenStack_1_0_NodeDriver
:members:
:inherited-members:
http://git-wip-us.apache.org/repos/asf/libcloud/blob/f7c81f65/docs/examples/compute/openstack/custom_service_catalog_selection_args.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/openstack/custom_service_catalog_selection_args.py b/docs/examples/compute/openstack/custom_service_catalog_selection_args.py
new file mode 100644
index 0000000..f05c266
--- /dev/null
+++ b/docs/examples/compute/openstack/custom_service_catalog_selection_args.py
@@ -0,0 +1,18 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+import libcloud.security
+
+# This assumes you don't have SSL set up.
+# Note: Code like this poses a security risk (MITM attack) and
+# that's the reason why you should never use it for anything else
+# besides testing. You have been warned.
+libcloud.security.VERIFY_SSL_CERT = False
+
+OpenStack = get_driver(Provider.OPENSTACK)
+driver = OpenStack('your_auth_username', 'your_auth_password',
+ ex_force_auth_url='http://192.168.1.101:5000/v2.0',
+ ex_force_auth_version='2.0_password',
+ ex_force_service_type='compute',
+ ex_force_service_name='novaCompute',
+ ex_force_service_region='MyRegion')
http://git-wip-us.apache.org/repos/asf/libcloud/blob/f7c81f65/docs/examples/compute/openstack/force_auth_token.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/openstack/force_auth_token.py b/docs/examples/compute/openstack/force_auth_token.py
new file mode 100644
index 0000000..90a0ee3
--- /dev/null
+++ b/docs/examples/compute/openstack/force_auth_token.py
@@ -0,0 +1,16 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+import libcloud.security
+
+# This assumes you don't have SSL set up.
+# Note: Code like this poses a security risk (MITM attack) and
+# that's the reason why you should never use it for anything else
+# besides testing. You have been warned.
+libcloud.security.VERIFY_SSL_CERT = False
+
+OpenStack = get_driver(Provider.OPENSTACK)
+driver = OpenStack('your_auth_username', 'your_auth_password',
+ ex_force_auth_url='http://192.168.1.101:5000/v2.0',
+ ex_force_auth_version='2.0_password',
+ ex_force_auth_token='authtoken')
http://git-wip-us.apache.org/repos/asf/libcloud/blob/f7c81f65/docs/examples/compute/openstack/force_base_url.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/openstack/force_base_url.py b/docs/examples/compute/openstack/force_base_url.py
new file mode 100644
index 0000000..560591b
--- /dev/null
+++ b/docs/examples/compute/openstack/force_base_url.py
@@ -0,0 +1,16 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+import libcloud.security
+
+# This assumes you don't have SSL set up.
+# Note: Code like this poses a security risk (MITM attack) and
+# that's the reason why you should never use it for anything else
+# besides testing. You have been warned.
+libcloud.security.VERIFY_SSL_CERT = False
+
+OpenStack = get_driver(Provider.OPENSTACK)
+driver = OpenStack('your_auth_username', 'your_auth_password',
+ ex_force_auth_url='http://192.168.1.101:5000/v2.0',
+ ex_force_auth_version='2.0_password',
+ ex_force_base_url='http://192.168.1.101:3000/v1')
http://git-wip-us.apache.org/repos/asf/libcloud/blob/f7c81f65/docs/examples/compute/openstack/simple_auth.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/openstack/simple_auth.py b/docs/examples/compute/openstack/simple_auth.py
new file mode 100644
index 0000000..65659c9
--- /dev/null
+++ b/docs/examples/compute/openstack/simple_auth.py
@@ -0,0 +1,15 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+import libcloud.security
+
+# This assumes you don't have SSL set up.
+# Note: Code like this poses a security risk (MITM attack) and
+# that's the reason why you should never use it for anything else
+# besides testing. You have been warned.
+libcloud.security.VERIFY_SSL_CERT = False
+
+OpenStack = get_driver(Provider.OPENSTACK)
+driver = OpenStack('your_auth_username', 'your_auth_password',
+ ex_force_auth_url='http://192.168.1.101:5000/v2.0',
+ ex_force_auth_version='2.0_password')
[2/3] git commit: docs: Link to the provider documentation page from
the provider matrix table.
Posted by to...@apache.org.
docs: Link to the provider documentation page from the provider matrix table.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/08662bef
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/08662bef
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/08662bef
Branch: refs/heads/trunk
Commit: 08662bef48cf0e6d5e4ff197542a9dbdd3c2a621
Parents: f7c81f6
Author: Tomaz Muraus <to...@apache.org>
Authored: Fri Oct 11 15:20:11 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Fri Oct 11 15:20:11 2013 +0200
----------------------------------------------------------------------
.../generate_provider_feature_matrix_table.py | 25 ++++++++++++++++----
1 file changed, 20 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/08662bef/contrib/generate_provider_feature_matrix_table.py
----------------------------------------------------------------------
diff --git a/contrib/generate_provider_feature_matrix_table.py b/contrib/generate_provider_feature_matrix_table.py
index 7f7c903..319d00f 100755
--- a/contrib/generate_provider_feature_matrix_table.py
+++ b/contrib/generate_provider_feature_matrix_table.py
@@ -232,16 +232,29 @@ def generate_supported_methods_table(api, provider_matrix):
return result
-def generate_supported_providers_table(provider_matrix):
+def generate_supported_providers_table(api, provider_matrix):
data = []
- header = ['Provider', 'Provider constant', 'Module', 'Class Name']
+ header = ['Provider', 'Documentation', 'Provider constant', 'Module',
+ 'Class Name']
data.append(header)
for provider, values in provider_matrix.items():
+
name_str = '`%s`_' % (values['name'])
module_str = ':mod:`%s`' % (values['module'])
class_str = ':class:`%s`' % (values['class'])
- row = [name_str, values['constant'], module_str, class_str]
+
+ params = {'api': api, 'provider': provider.lower()}
+ driver_docs_path = pjoin(this_dir,
+ '../docs/%(api)s/drivers/%(provider)s.rst'
+ % params)
+
+ if os.path.exists(driver_docs_path):
+ docs_link = ':doc:`Click </%(api)s/drivers/%(provider)s>`' % params
+ else:
+ docs_link = ''
+
+ row = [name_str, docs_link, values['constant'], module_str, class_str]
data.append(row)
result = generate_rst_table(data)
@@ -256,8 +269,6 @@ def generate_tables():
apis = BASE_API_METHODS.keys()
for api in apis:
result = generate_providers_table(api)
- supported_providers = generate_supported_providers_table(result)
- supported_methods = generate_supported_methods_table(api, result)
docs_dir = api
@@ -266,6 +277,10 @@ def generate_tables():
elif api.startswith('storage'):
docs_dir = 'storage'
+ supported_providers = generate_supported_providers_table(docs_dir,
+ result)
+ supported_methods = generate_supported_methods_table(api, result)
+
current_path = os.path.dirname(__file__)
target_dir = os.path.abspath(pjoin(current_path,
'../docs/%s/' % (docs_dir)))
[3/3] git commit: docs: Display providers in the supported providers
and supported methods table in an alphabetical order.
Posted by to...@apache.org.
docs: Display providers in the supported providers and supported methods table
in an alphabetical order.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/8a4c4a80
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/8a4c4a80
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/8a4c4a80
Branch: refs/heads/trunk
Commit: 8a4c4a80f640213aa3301fff2fc844e02922eda0
Parents: 08662be
Author: Tomaz Muraus <to...@apache.org>
Authored: Fri Oct 11 15:23:27 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Fri Oct 11 15:23:27 2013 +0200
----------------------------------------------------------------------
contrib/generate_provider_feature_matrix_table.py | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/8a4c4a80/contrib/generate_provider_feature_matrix_table.py
----------------------------------------------------------------------
diff --git a/contrib/generate_provider_feature_matrix_table.py b/contrib/generate_provider_feature_matrix_table.py
index 319d00f..0f674c6 100755
--- a/contrib/generate_provider_feature_matrix_table.py
+++ b/contrib/generate_provider_feature_matrix_table.py
@@ -214,7 +214,7 @@ def generate_supported_methods_table(api, provider_matrix):
base_api_methods]
data.append(['Provider'] + header)
- for provider, values in provider_matrix.items():
+ for provider, values in sorted(provider_matrix.items()):
provider_name = '`%s`_' % (values['name'])
row = [provider_name]
for _, supported in values['methods'].items():
@@ -227,7 +227,7 @@ def generate_supported_methods_table(api, provider_matrix):
result = generate_rst_table(data)
result += '\n\n'
- for provider, values in provider_matrix.items():
+ for provider, values in sorted(provider_matrix.items()):
result += '.. _`%s`: %s\n' % (values['name'], values['website'])
return result
@@ -238,7 +238,7 @@ def generate_supported_providers_table(api, provider_matrix):
'Class Name']
data.append(header)
- for provider, values in provider_matrix.items():
+ for provider, values in sorted(provider_matrix.items()):
name_str = '`%s`_' % (values['name'])
module_str = ':mod:`%s`' % (values['module'])
@@ -260,7 +260,7 @@ def generate_supported_providers_table(api, provider_matrix):
result = generate_rst_table(data)
result += '\n\n'
- for provider, values in provider_matrix.items():
+ for provider, values in sorted(provider_matrix.items()):
result += '.. _`%s`: %s\n' % (values['name'], values['website'])
return result