diff --git a/doc/source/index.rst b/doc/source/index.rst index d1f585e..f663a0c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,10 +13,10 @@ User documentation .. toctree:: :maxdepth: 2 - user + user/index Developer documentation ----------------------- +----------------------- .. toctree:: :maxdepth: 2 diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index 6f8f188..0000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,53 +0,0 @@ -============ -Installation -============ - -Note that ooi is still under development, so documentation is a bit naive. In -order to install and test ooi, perform the steps below. - -Get the latest source code:: - - $ git clone https://github.com/stackforge/ooi.git - -Install it:: - - $ cd ooi - $ pip install . - -Add it to your OpenStack installation. Edit your ``/etc/nova/api-paste.ini``. -In the ``[composite:osapi_compute]`` add the following:: - - [composite:osapi_compute] - # (...) - /occi1.1: occi_11 - -Afterwards, add the OCCI filter like this:: - - [filter:occi] - paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory - openstack_version = /v2 - -Substitute ``openstack_version`` with the API version that you are going to -use, taken from the ``[composite:osapi_compute]`` section. So far we have -tested it with the ``v2`` version, so the correct value should be ``/v2``. - -The last step is to duplicate the ``composite`` section corresponding to the -configured version, rename it to the configured value above (in this case -we have used ``occi_11`` above), and adding the ``occi`` filter just before the -``osapi_compute_app`` component of the pipeline. So, in this case where ``v2`` -has been configured, the ``[composite:openstack_compute_api_v2]`` should be -duplicated as follows:: - - [composite:occi_11] - use = call:nova.api.auth:pipeline_factory - noauth = compute_req_id faultwrap sizelimit noauth ratelimit occi osapi_compute_app_v2 - keystone = compute_req_id faultwrap sizelimit occi authtoken keystonecontext ratelimit occi osapi_compute_app_v2 - keystone_nolimit = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v2 - -If everything is OK, after rebooting the ``nova-api`` service you should be able -to access your OCCI endpoint at:: - - $ nova credentials - # Grab the token - $ export KID= - $ curl -H "x-auth-token: $KID" http://localhost:8774/occi1.1/-/ diff --git a/doc/source/user/configuration.rst b/doc/source/user/configuration.rst new file mode 100644 index 0000000..d7b8c86 --- /dev/null +++ b/doc/source/user/configuration.rst @@ -0,0 +1,57 @@ +Configuration +============= + +Once installed it is needed to add it to your OpenStack installation. Edit your +``/etc/nova/api-paste.ini``. + +First it is needed to add a the OCCI filter like this:: + + [filter:occi] + paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory + openstack_version = /v2 + +``openstack_version`` can be configured to any of the supported OpenStack API +versions, as indicated in Table :ref:`api-versions`. If it is not configured, by +default it will take the ``/v2.1`` value. + +.. _api-versions: + +.. table:: Supported OpenStack API versions + + ===================== ===================== ============================================= + OpenStack API version ``openstack_version`` corresponding OpenStack ``composite`` section + ===================== ===================== ============================================= + v2 ``/v2`` ``[composite:openstack_compute_api_v2]`` + v2.1 ``/v2.1`` ``[composite:openstack_compute_api_v21]`` + ===================== ===================== ============================================= + +The next step is to create a ``composite`` section for the OCCI interface. It +is needed to duplicate the :ref:`corresponding OpenStack API ``composite``` section, +renaming it to ``occi_api_v11``. Once duplicated, the ``occi`` middleware needs +to be added just before the last component of the pipeline. So, in the example +above where ``/v2`` has been configured, we need to duplicate the +``[composite:openstack_compute_api_v2]`` as follows:: + + [composite:occi_api_v11] + use = call:nova.api.auth:pipeline_factory + noauth = compute_req_id faultwrap sizelimit noauth ratelimit occi osapi_compute_app_v2 + keystone = compute_req_id faultwrap sizelimit occi authtoken keystonecontext ratelimit occi osapi_compute_app_v2 + keystone_nolimit = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v2 + +The last step is to add it to the ``[composite:osapi_compute]`` section:: + + [composite:osapi_compute] + # (...) + /occi1.1: occi_api_11 + +You can find more detailed examples regarding the pipeline configuration in the +:ref:`pipeline-examples` section. + +If everything is OK, after rebooting the ``nova-api`` service you should be able +to access your OCCI endpoint at:: + + $ nova credentials + # Grab the token + $ export KID= + $ curl -H "x-auth-token: $KID" http://localhost:8774/occi1.1/-/ + diff --git a/doc/source/user.rst b/doc/source/user/index.rst similarity index 70% rename from doc/source/user.rst rename to doc/source/user/index.rst index 0ebad97..01788b2 100644 --- a/doc/source/user.rst +++ b/doc/source/user/index.rst @@ -5,3 +5,5 @@ User documentation :maxdepth: 2 installation + configuration + pipelines/index diff --git a/doc/source/user/installation.rst b/doc/source/user/installation.rst new file mode 100644 index 0000000..4e6382e --- /dev/null +++ b/doc/source/user/installation.rst @@ -0,0 +1,11 @@ +Installation +============ + +Get the latest source code:: + + $ git clone https://github.com/stackforge/ooi.git + +Install it:: + + $ cd ooi + $ pip install . diff --git a/doc/source/user/pipelines/index.rst b/doc/source/user/pipelines/index.rst new file mode 100644 index 0000000..2aff330 --- /dev/null +++ b/doc/source/user/pipelines/index.rst @@ -0,0 +1,22 @@ +.. _pipeline-examples: + +Pipeline examples +================= + +For your convenience, find below some example pipelines to be used with the +corresponding OpenStack Compute version. These are to be **added** into your +``/etc/nova/api-paste.ini`` configuration file. Take into account that you do +not have to duplicate the ``[composite:osapi_compute]`` section, but just add +the OCCI relevant line. These are just examples, so take into account that +your pipeline may actually differ. + +.. include:: juno.rst +.. include:: kilo.rst + +.. # NOTE(aloga): We are including the pipelines, so we are not adding them to + # any TOC and sphinx will complain. +.. toctree:: + :hidden: + + juno + kilo diff --git a/doc/source/user/pipelines/juno.rst b/doc/source/user/pipelines/juno.rst new file mode 100644 index 0000000..d22510c --- /dev/null +++ b/doc/source/user/pipelines/juno.rst @@ -0,0 +1,22 @@ +Juno (2014.2) +------------- + +.. code:: ini + + [composite:osapi_compute] + use = call:nova.api.openstack.urlmap:urlmap_factory + /: oscomputeversions + /v1.1: openstack_compute_api_v2 + /v2: openstack_compute_api_v2 + /v2.1: openstack_compute_api_v21 + /v3: openstack_compute_api_v3 + /occi1.1: occi_api_11 + + [filter:occi] + paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory + openstack_version = /v2.1 + + [composite:occi_api_11] + use = call:nova.api.auth:pipeline_factory_v21 + noauth = compute_req_id faultwrap sizelimit noauth occi osapi_compute_app_v21 + keystone = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v21 diff --git a/doc/source/user/pipelines/kilo.rst b/doc/source/user/pipelines/kilo.rst new file mode 100644 index 0000000..e7e6bf4 --- /dev/null +++ b/doc/source/user/pipelines/kilo.rst @@ -0,0 +1,23 @@ +Kilo (2015.1) +------------- + +.. code:: ini + + [composite:osapi_compute] + use = call:nova.api.openstack.urlmap:urlmap_factory + /: oscomputeversions + /v1.1: openstack_compute_api_v2 + /v2: openstack_compute_api_v2 + /v2.1: openstack_compute_api_v21 + /v3: openstack_compute_api_v3 + /occi1.1: occi_api_11 + + [filter:occi] + paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory + openstack_version = /v2.1 + + [composite:occi_api_11] + use = call:nova.api.auth:pipeline_factory_v21 + noauth = compute_req_id faultwrap sizelimit noauth occi osapi_compute_app_v21 + noauth2 = compute_req_id faultwrap sizelimit noauth2 occi osapi_compute_app_v21 + keystone = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v21