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 <[email protected]> Authored: Fri Oct 11 15:06:14 2013 +0200 Committer: Tomaz Muraus <[email protected]> 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')
