diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | docs/etc/conf.py | 34 | ||||
| -rw-r--r-- | docs/etc/opnfv-logo.png | bin | 0 -> 2829 bytes | |||
| -rw-r--r-- | docs/how-to-use-docs/documentation-example.rst | 86 | ||||
| -rw-r--r-- | docs/how-to-use-docs/index.rst | 30 | ||||
| -rw-r--r-- | manuals/mark-host-down_manual.rst | 109 |
6 files changed, 260 insertions, 0 deletions
@@ -1 +1,2 @@ build/ +public/ diff --git a/docs/etc/conf.py b/docs/etc/conf.py new file mode 100644 index 00000000..00660351 --- /dev/null +++ b/docs/etc/conf.py @@ -0,0 +1,34 @@ +import datetime +import sys +import os + +try: + __import__('imp').find_module('sphinx.ext.numfig') + extensions = ['sphinx.ext.numfig'] +except ImportError: + # 'pip install sphinx_numfig' + extensions = ['sphinx_numfig'] + +# numfig: +number_figures = True +figure_caption_prefix = "Fig." + +source_suffix = '.rst' +master_doc = 'index' +pygments_style = 'sphinx' +html_use_index = False + +pdf_documents = [('index', u'OPNFV', u'OPNFV Project', u'OPNFV')] +pdf_fit_mode = "shrink" +pdf_stylesheets = ['sphinx','kerning','a4'] +#latex_domain_indices = False +#latex_use_modindex = False + +latex_elements = { + 'printindex': '', +} + +project = u'OPNFV: Template documentation config' +copyright = u'%s, OPNFV' % datetime.date.today().year +version = u'1.0.0' +release = u'1.0.0' diff --git a/docs/etc/opnfv-logo.png b/docs/etc/opnfv-logo.png Binary files differnew file mode 100644 index 00000000..1519503e --- /dev/null +++ b/docs/etc/opnfv-logo.png diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst new file mode 100644 index 00000000..afcf7581 --- /dev/null +++ b/docs/how-to-use-docs/documentation-example.rst @@ -0,0 +1,86 @@ +.. two dots create a comment. please leave this logo at the top of each of your rst files. +.. image:: ../etc/opnfv-logo.png + :height: 40 + :width: 200 + :alt: OPNFV + :align: left +.. these two pipes are to seperate the logo from the first title +| +| +How to create documentation for your OPNFV project +================================================== + +this is the directory structure of the docs/ directory that can be found in the root of your project directory + +.. code-block:: bash + + ./etc + ./etc/opnfv-logo.png + ./etc/conf.py + ./how-to-use-docs + ./how-to-use-docs/documentation-example.rst + ./how-to-use-docs/index.rst + +To create your own documentation, Create any number of directories (depending on your need) and place in each of them an index.rst. +This index file must refence your other rst files. + +* Here is an example index.rst + +.. code-block:: bash + + Example Documentation table of contents + ======================================= + + Contents: + + .. toctree:: + :numbered: + :maxdepth: 4 + + documentation-example.rst + + Indices and tables + ================== + + * :ref:`search` + + Revision: _sha1_ + + Build date: |today| + + +The Sphinx Build +================ + +When you push documentation changes to gerrit a jenkins job will create html documentation. + +* Verify Jobs +For verify jobs a link to the documentation will show up as a comment in gerrit for you to see the result. + +* Merge jobs + +Once you are happy with the look of your documentation you can submit the patchset the merge job will +copy the output of each documentation directory to http://artifacts.opnfv.org/$project/docs/$name_of_your_folder/index.html + +Here are some quick examples of how to use rst markup + +This is a headline:: + + here is some code, note that it is indented + +links are easy to add: Here is a link to sphinx, the tool that we are using to generate documetation http://sphinx-doc.org/ + +* Bulleted Items + + **this will be bold** + +.. code-block:: bash + + echo "Heres is a code block with bash syntax highlighting" + + +Leave these at the bottom of each of your documents they are used internally + +Revision: _sha1_ + +Build date: |today| diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst new file mode 100644 index 00000000..36710b32 --- /dev/null +++ b/docs/how-to-use-docs/index.rst @@ -0,0 +1,30 @@ +.. OPNFV Release Engineering documentation, created by + sphinx-quickstart on Tue Jun 9 19:12:31 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. image:: ../etc/opnfv-logo.png + :height: 40 + :width: 200 + :alt: OPNFV + :align: left + +Example Documentation table of contents +======================================= + +Contents: + +.. toctree:: + :numbered: + :maxdepth: 4 + + documentation-example.rst + +Indices and tables +================== + +* :ref:`search` + +Revision: _sha1_ + +Build date: |today| diff --git a/manuals/mark-host-down_manual.rst b/manuals/mark-host-down_manual.rst new file mode 100644 index 00000000..499644f7 --- /dev/null +++ b/manuals/mark-host-down_manual.rst @@ -0,0 +1,109 @@ +OpenStack NOVA API for marking host down. + +Related Blueprints: + + https://blueprints.launchpad.net/nova/+spec/mark-host-down + https://blueprints.launchpad.net/python-novaclient/+spec/support-force-down-service + +What the API is for + + This API will give external fault monitoring system a possibility of telling + OpenStack Nova fast that compute host is down. This will immediately enable + calling of evacuation of any VM on host and further enabling faster HA + actions. + +What this API does + + In OpenStack the nova-compute service state can represent the compute host + state and this new API is used to force this service down. It is assumed + that the one calling this API has made sure the host is also fenced or + powered down. This is important, so there is no chance same VM instance will + appear twice in case evacuated to new compute host. When host is recovered + by any means, the external system is responsible of calling the API again to + disable forced_down flag and let the host nova-compute service report again + host being up. If network fenced host come up again it should not boot VMs + it had if figuring out they are evacuated to other compute host. The + decision of deleting or booting VMs there used to be on host should be + enhanced later to be more reliable by Nova blueprint: + https://blueprints.launchpad.net/nova/+spec/robustify-evacuate + +REST API for forcing down: + + Parameter explanations: + tenant_id: Identifier of the tenant. + binary: Compute service binary name. + host: Compute host name. + forced_down: Compute service forced down flag. + token: Token received after successful authentication. + service_host_ip: Serving controller node ip. + + request: + PUT /v2.1/{tenant_id}/os-services/force-down + { + "binary": "nova-compute", + "host": "compute1", + "forced_down": true + } + + response: + 200 OK + { + "service": { + "host": "compute1", + "binary": "nova-compute", + "forced_down": true + } + } + + Example: + curl -g -i -X PUT http://{service_host_ip}:8774/v2.1/{tenant_id}/os-services + /force-down -H "Content-Type: application/json" -H "Accept: application/json + " -H "X-OpenStack-Nova-API-Version: 2.11" -H "X-Auth-Token: {token}" -d '{"b + inary": "nova-compute", "host": "compute1", "forced_down": true}' + +CLI for forcing down: + + nova service-force-down <hostname> nova-compute + + Example: + nova service-force-down compute1 nova-compute + +REST API for disabling forced down: + + Parameter explanations: + tenant_id: Identifier of the tenant. + binary: Compute service binary name. + host: Compute host name. + forced_down: Compute service forced down flag. + token: Token received after successful authentication. + service_host_ip: Serving controller node ip. + + request: + PUT /v2.1/{tenant_id}/os-services/force-down + { + "binary": "nova-compute", + "host": "compute1", + "forced_down": false + } + + response: + 200 OK + { + "service": { + "host": "compute1", + "binary": "nova-compute", + "forced_down": false + } + } + + Example: + curl -g -i -X PUT http://{service_host_ip}:8774/v2.1/{tenant_id}/os-services + /force-down -H "Content-Type: application/json" -H "Accept: application/json + " -H "X-OpenStack-Nova-API-Version: 2.11" -H "X-Auth-Token: {token}" -d '{"b + inary": "nova-compute", "host": "compute1", "forced_down": false}' + +CLI for disabling forced down: + nova service-force-down --unset <hostname> nova-compute + + Example: + nova service-force-down --unset compute1 nova-compute |
