Add httpd documentation and sample configs

This adds uwsgi sample configs and documentation for
deploying api services with httpd.

This moves the existing mod_wsgi sample configs from devtsack
folder as they are not specific to devstack.

Change-Id: I91fd64d9deba3371b62c00ba8b01a7aca21b2393

devstack/files/apache-heat-pip-repo.template

@@ -1,15 +0,0 @@
-Listen %HEAT_PIP_REPO_PORT%
-
-<VirtualHost *:%HEAT_PIP_REPO_PORT%>
-    DocumentRoot %HEAT_PIP_REPO%
-    <Directory %HEAT_PIP_REPO%>
-        DirectoryIndex index.html
-        Require all granted
-        Order allow,deny
-        allow from all
-    </Directory>
-
-    ErrorLog /var/log/%APACHE_NAME%/heat_pip_repo_error.log
-    LogLevel warn
-    CustomLog /var/log/%APACHE_NAME%/heat_pip_repo_access.log combined
-</VirtualHost>

devstack/files/debs/heat

@@ -1 +0,0 @@
-gettext # dist:trusty

devstack/lib/heat

@@ -43,7 +43,7 @@ GITBRANCH["python-heatclient"]=${HEATCLIENT_BRANCH:-master}
 HEAT_USE_APACHE=${HEAT_USE_APACHE:-${HEAT_USE_MOD_WSGI:-True}}
 
 HEAT_DIR=$DEST/heat
-HEAT_FILES_DIR=$HEAT_DIR/devstack/files
+HEAT_FILES_DIR=$HEAT_DIR/heat/httpd/files
 
 HEAT_AUTH_CACHE_DIR=${HEAT_AUTH_CACHE_DIR:-/var/cache/heat}
 HEAT_STANDALONE=$(trueorfalse False HEAT_STANDALONE)
@@ -61,9 +61,9 @@ HEAT_TRUSTEE_DOMAIN=${HEAT_TRUSTEE_DOMAIN:-default}
 
 # Support entry points installation of console scripts
 HEAT_BIN_DIR=$(get_python_exec_prefix)
-HEAT_API_UWSGI_CONF=$HEAT_CONF_DIR/heat-uwsgi-api.ini
+HEAT_API_UWSGI_CONF=$HEAT_CONF_DIR/heat-api-uwsgi.ini
-HEAT_CFN_API_UWSGI_CONF=$HEAT_CONF_DIR/heat-uwsgi-cfn-api.ini
+HEAT_CFN_API_UWSGI_CONF=$HEAT_CONF_DIR/heat-api-cfn-uwsgi.ini
-HEAT_CW_API_UWSGI_CONF=$HEAT_CONF_DIR/heat-uwsgi-cw-api.ini
+HEAT_CW_API_UWSGI_CONF=$HEAT_CONF_DIR/heat-api-cloudwatch-uwsgi.ini
 HEAT_API_UWSGI=$HEAT_BIN_DIR/heat-wsgi-api
 HEAT_CFN_API_UWSGI=$HEAT_BIN_DIR/heat-wsgi-api-cfn
 HEAT_CW_API_UWSGI=$HEAT_BIN_DIR/heat-wsgi-api-cloudwatch
@@ -394,7 +394,7 @@ function _config_heat_apache_wsgi {
     local heat_cw_api_port=$HEAT_API_CW_PORT
     local venv_path=""
 
-    sudo cp $HEAT_FILES_DIR/apache-heat-api.template $heat_apache_conf
+    sudo cp $HEAT_FILES_DIR/heat-api.conf $heat_apache_conf
     sudo sed -e "
         s|%PUBLICPORT%|$heat_api_port|g;
         s|%APACHE_NAME%|$APACHE_NAME|g;
@@ -407,7 +407,7 @@ function _config_heat_apache_wsgi {
         s|%VIRTUALENV%|$venv_path|g
     " -i $heat_apache_conf
 
-    sudo cp $HEAT_FILES_DIR/apache-heat-api-cfn.template $heat_cfn_apache_conf
+    sudo cp $HEAT_FILES_DIR/heat-api-cfn.conf $heat_cfn_apache_conf
     sudo sed -e "
         s|%PUBLICPORT%|$heat_cfn_api_port|g;
         s|%APACHE_NAME%|$APACHE_NAME|g;
@@ -420,7 +420,7 @@ function _config_heat_apache_wsgi {
         s|%VIRTUALENV%|$venv_path|g
     " -i $heat_cfn_apache_conf
 
-    sudo cp $HEAT_FILES_DIR/apache-heat-api-cloudwatch.template $heat_cloudwatch_apache_conf
+    sudo cp $HEAT_FILES_DIR/heat-api-cloudwatch.conf $heat_cloudwatch_apache_conf
     sudo sed -e "
         s|%PUBLICPORT%|$heat_cw_api_port|g;
         s|%APACHE_NAME%|$APACHE_NAME|g;

doc/source/index.rst

@@ -63,6 +63,7 @@ Operating Heat
     getting_started/on_fedora
     getting_started/on_ubuntu
     operating_guides/scale_deployment
+    operating_guides/httpd
     man/index
 
 Developing Heat

doc/source/operating_guides/httpd.rst

@@ -0,0 +1,109 @@
+========================================
+Running Heat API services in HTTP Server
+========================================
+
+Since the Liberty release Heat has packaged a set of wsgi script entrypoints
+that enables users to run api services with a real web server like Apache
+HTTP Server (httpd).
+
+There are several patterns for deployment. This doc shows some common ways of
+deploying api services with httpd.
+
+mod-wsgi
+--------
+
+This deployment method is possible since Liberty release.
+
+The httpd/files directory contains sample files that can be changed and
+copied to the appropriate location in your httpd server.
+
+On Debian/Ubuntu systems it is::
+
+    /etc/apache2/sites-available/heat-api.conf
+    /etc/apache2/sites-available/heat-api-cfn.conf
+    /etc/apache2/sites-available/heat-api-cloudwatch.conf
+
+On Red Hat based systems it is::
+
+    /etc/httpd/conf.d/uwsgi-heat-api.conf
+    /etc/httpd/conf.d/uwsgi-heat-api-cfn.conf
+    /etc/httpd/conf.d/uwsgi-heat-api-cloudwatch.conf
+
+uwsgi
+-----
+
+In this deployment method we use uwsgi as a web server bound to a random local
+port. Then we configure apache using mod_proxy to forward all incoming requests
+on the specified endpoint to that local webserver. This has the advantage of
+letting apache manage all inbound http connections, and uwsgi manage running
+the python code. It also means when we make changes to Heat api code or
+configuration, we don't need to restart all of apache (which may be running
+other services too) and just need to restart the local uwsgi daemons.
+
+The httpd/files directory contains sample files for configuring httpd to run
+Heat api services under uwsgi in this configuration. To use the sample configs
+simply copy `uwsgi-heat-api.conf`, `uwsgi-heat-api-cfn.conf` and
+`uwsgi-heat-api-cloudwatch.conf` to the appropriate location for your web server.
+
+On Debian/Ubuntu systems it is::
+
+    /etc/apache2/sites-available/uwsgi-heat-api.conf
+    /etc/apache2/sites-available/uwsgi-heat-api-cfn.conf
+    /etc/apache2/sites-available/uwsgi-heat-api-cloudwatch.conf
+
+On Red Hat based systems it is::
+
+    /etc/httpd/conf.d/uwsgi-heat-api.conf
+    /etc/httpd/conf.d/uwsgi-heat-api-cfn.conf
+    /etc/httpd/conf.d/uwsgi-heat-api-cloudwatch.conf
+
+Enable mod_proxy by running ``sudo a2enmod proxy``
+
+Then on Ubuntu/Debian systems enable the site by creating a symlink from the
+file in ``sites-available`` to ``sites-enabled``. (This is not required on
+Red Hat based systems)::
+
+    ln -s /etc/apache2/sites-available/uwsgi-heat-api.conf /etc/apache2/sites-enabled
+    ln -s /etc/apache2/sites-available/uwsgi-heat-api-cfn.conf /etc/apache2/sites-enabled
+    ln -s /etc/apache2/sites-available/uwsgi-heat-api-cloudwatch.conf /etc/apache2/sites-enabled
+
+Start or restart httpd to pick up the new configuration.
+
+Now we need to configure and start the uwsgi service. Copy the following
+files to `/etc/heat`::
+
+        heat-api-uwsgi.ini
+        heat-api-cfn-uwsgi.ini
+        heat-api-cloudwatch-uwsgi.ini
+
+Update the files to match your system configuration (for example, you'll
+want to set the number of processes and threads).
+
+Install uwsgi and start the heat-api server using uwsgi::
+
+    sudo pip install uwsgi
+    uwsgi --ini /etc/heat/heat-api-uwsgi.ini
+    uwsgi --ini /etc/heat/heat-api-cfn-uwsgi.ini
+    uwsgi --ini /etc/heat/heat-api-cloudwatch-uwsgi.ini
+
+.. NOTE::
+
+    In the sample configs some random ports are used, but this doesn't matter
+    and is just a randomly selected number. This is not a contract on the port
+    used for the local uwsgi daemon.
+
+
+mod_proxy_uwsgi
+'''''''''''''''
+
+Instead of running uwsgi as a webserver listening on a local port and then
+having Apache HTTP proxy all the incoming requests with mod_proxy, the
+normally recommended way of deploying uwsgi with Apache httpd is to use
+mod_proxy_uwsgi and set up a local socket file for uwsgi to listen on. Apache
+will send the requests using the uwsgi protocol over this local socket
+file.
+
+The dsvm jobs in heat upstream gate uses this deployment method.
+
+For more details on using mod_proxy_uwsgi see the official docs:
+http://uwsgi-docs.readthedocs.io/en/latest/Apache.html?highlight=mod_uwsgi_proxy#mod-proxy-uwsgi

heat/httpd/files/heat-api-cfn-uwsgi.ini

@@ -0,0 +1,14 @@
+[uwsgi]
+chmod-socket = 666
+lazy-apps = true
+add-header = Connection: close
+buffer-size = 65535
+thunder-lock = true
+plugins = python
+enable-threads = true
+exit-on-reload = true
+die-on-term = true
+master = true
+processes = 4
+http = 127.0.0.1:80998
+wsgi-file = /usr/local/bin/heat-wsgi-api-cfn

heat/httpd/files/heat-api-cloudwatch-uwsgi.ini

@@ -0,0 +1,14 @@
+[uwsgi]
+chmod-socket = 666
+lazy-apps = true
+add-header = Connection: close
+buffer-size = 65535
+thunder-lock = true
+plugins = python
+enable-threads = true
+exit-on-reload = true
+die-on-term = true
+master = true
+processes = 4
+http = 127.0.0.1:80997
+wsgi-file = /usr/local/bin/heat-wsgi-api-cloudwatch

heat/httpd/files/heat-api-uwsgi.ini

@@ -0,0 +1,14 @@
+[uwsgi]
+chmod-socket = 666
+lazy-apps = true
+add-header = Connection: close
+buffer-size = 65535
+thunder-lock = true
+plugins = python
+enable-threads = true
+exit-on-reload = true
+die-on-term = true
+master = true
+processes = 4
+http = 127.0.0.1:80999
+wsgi-file = /usr/local/bin/heat-wsgi-api

heat/httpd/files/uwsgi-heat-api-cfn.conf

@@ -0,0 +1,2 @@
+KeepAlive Off
+ProxyPass "/heat-api-cfn" "http://127.0.0.1:80998" retry=0

heat/httpd/files/uwsgi-heat-api-cloudwatch.conf

@@ -0,0 +1,2 @@
+KeepAlive Off
+ProxyPass "/heat-api-cloudwatch" "http://127.0.0.1:80997" retry=0

heat/httpd/files/uwsgi-heat-api.conf

@@ -0,0 +1,2 @@
+KeepAlive Off
+ProxyPass "/heat-api" "http://127.0.0.1:80999" retry=0