devref and reno for nova-{api,metadata}-wsgi scripts

This provides a brief explanation of the new nova-api-wsgi [1] and
nova-metadata-wsgi [2] scripts in the Architecture section of the devref
with links to the new doc added to the man pages for the eventlet
scripts.

The nova-api.rst mentioned ec2 so figured best to fix that now
rather than forget about it, despite not being entirely germane.

There is also a reno note that indicates the availability of the new
scripts.

There is a devstack change which is testing the new wsgi scripts as
well as forcing grenade to not use them at
If2d7e363a6541854f2e30c03171bef7a41aff745

[1] I7c4acfaa6c50ac0e4d6de69eb62ec5bbad72ff85
[2] Icb35fe2b94ab02c0ba8ba8129ae18aae0f794756

Change-Id: I351b2af3b256d3031bd2a65feba0495e815f8427
Related-Bug: #1661360

doc/source/index.rst

@@ -159,6 +159,7 @@ Open Development.
    quotas
    threading
    vmstates
+   wsgi
 
 Architecture Evolution Plans
 -----------------------------

doc/source/man/nova-api-metadata.rst

@@ -41,6 +41,7 @@ SEE ALSO
 ========
 
 * `OpenStack Nova <https://docs.openstack.org/developer/nova>`__
+* `Using WSGI with Nova <https://docs.openstack.org/devloper/nova/wsgi.html>`__
 
 BUGS
 ====

doc/source/man/nova-api-os-compute.rst

@@ -41,6 +41,7 @@ SEE ALSO
 ========
 
 * `OpenStack Nova <https://docs.openstack.org/developer/nova>`__
+* `Using WSGI with Nova <https://docs.openstack.org/devloper/nova/wsgi.html>`__
 
 BUGS
 ====

doc/source/man/nova-api.rst

@@ -21,7 +21,8 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-nova-api is a server daemon that serves the nova EC2 and OpenStack APIs in separate greenthreads
+nova-api is a server daemon that serves the metadata and compute APIs in
+separate greenthreads
 
 OPTIONS
 =======
@@ -41,6 +42,7 @@ SEE ALSO
 ========
 
 * `OpenStack Nova <https://docs.openstack.org/developer/nova>`__
+* `Using WSGI with Nova <https://docs.openstack.org/devloper/nova/wsgi.html>`__
 
 BUGS
 ====

doc/source/wsgi.rst

@@ -0,0 +1,36 @@
+Using WSGI with Nova
+====================
+
+Though the compute and metadata APIs can be run using independent scripts that
+provide eventlet-based HTTP servers, it is generally considered more performant
+and flexible to run them using a generic HTTP server that supports WSGI_ (such
+as Apache_ or nginx_).
+
+The nova project provides two automatically generated entry points that
+support this: ``nova-api-wsgi`` and ``nova-metadata-wsgi``. These read
+``nova.conf`` and ``api-paste.ini`` and generate the required module-level
+``application`` that most WSGI servers require. If nova is installed using pip,
+these two scripts will be installed into whatever the expected ``bin``
+directory is for the environment.
+
+The new scripts replace older experimental scripts that could be found in the
+``nova/wsgi`` directory of the code repository. The new scripts are *not*
+experimental.
+
+When running the compute and metadata services with WSGI, sharing the compute
+and metadata service in the same process is not supported (as it is in the
+eventlet-based scripts).
+
+In devstack as of May 2017, the compute and metadata APIs are hosted by a
+Apache communicating with uwsgi_ via mod_proxy_uwsgi_. Inspecting the
+configuration created there can provide some guidance on one option for
+managing the WSGI scripts. It is important to remember, however, that one of
+the major features of using WSGI is that there are many different ways to host
+a WSGI application. Different servers make different choices about performance
+and configurability.
+
+.. _WSGI: https://www.python.org/dev/peps/pep-3333/
+.. _apache: http://httpd.apache.org/
+.. _nginx: http://nginx.org/en/
+.. _uwsgi: https://uwsgi-docs.readthedocs.io/
+.. _mod_proxy_uwsgi: http://uwsgi-docs.readthedocs.io/en/latest/Apache.html#mod-proxy-uwsgi

releasenotes/notes/wsgi-applications-8017c3192d2b143e.yaml

@@ -0,0 +1,8 @@
+---
+upgrade:
+  - |
+    WSGI application scripts ``nova-api-wsgi`` and ``nova-metadata-wsgi`` are
+    now available. They allow running the compute and metadata APIs using a WSGI
+    server of choice (for example nginx and uwsgi, apache2 with mod_proxy_uwsgx
+    or gunicorn). The eventlet-based servers are still available, but the WSGI
+    options will allow greater deployment flexibility.