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
This commit is contained in:
rabi 2017-06-27 18:26:27 +05:30
parent 645c58b12f
commit bcd8c814b7
14 changed files with 165 additions and 23 deletions

View File

@ -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>

View File

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

View File

@ -43,7 +43,7 @@ GITBRANCH["python-heatclient"]=${HEATCLIENT_BRANCH:-master}
HEAT_USE_APACHE=${HEAT_USE_APACHE:-${HEAT_USE_MOD_WSGI:-True}} HEAT_USE_APACHE=${HEAT_USE_APACHE:-${HEAT_USE_MOD_WSGI:-True}}
HEAT_DIR=$DEST/heat 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_AUTH_CACHE_DIR=${HEAT_AUTH_CACHE_DIR:-/var/cache/heat}
HEAT_STANDALONE=$(trueorfalse False HEAT_STANDALONE) HEAT_STANDALONE=$(trueorfalse False HEAT_STANDALONE)
@ -61,9 +61,9 @@ HEAT_TRUSTEE_DOMAIN=${HEAT_TRUSTEE_DOMAIN:-default}
# Support entry points installation of console scripts # Support entry points installation of console scripts
HEAT_BIN_DIR=$(get_python_exec_prefix) 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_API_UWSGI=$HEAT_BIN_DIR/heat-wsgi-api
HEAT_CFN_API_UWSGI=$HEAT_BIN_DIR/heat-wsgi-api-cfn HEAT_CFN_API_UWSGI=$HEAT_BIN_DIR/heat-wsgi-api-cfn
HEAT_CW_API_UWSGI=$HEAT_BIN_DIR/heat-wsgi-api-cloudwatch 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 heat_cw_api_port=$HEAT_API_CW_PORT
local venv_path="" 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 " sudo sed -e "
s|%PUBLICPORT%|$heat_api_port|g; s|%PUBLICPORT%|$heat_api_port|g;
s|%APACHE_NAME%|$APACHE_NAME|g; s|%APACHE_NAME%|$APACHE_NAME|g;
@ -407,7 +407,7 @@ function _config_heat_apache_wsgi {
s|%VIRTUALENV%|$venv_path|g s|%VIRTUALENV%|$venv_path|g
" -i $heat_apache_conf " -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 " sudo sed -e "
s|%PUBLICPORT%|$heat_cfn_api_port|g; s|%PUBLICPORT%|$heat_cfn_api_port|g;
s|%APACHE_NAME%|$APACHE_NAME|g; s|%APACHE_NAME%|$APACHE_NAME|g;
@ -420,7 +420,7 @@ function _config_heat_apache_wsgi {
s|%VIRTUALENV%|$venv_path|g s|%VIRTUALENV%|$venv_path|g
" -i $heat_cfn_apache_conf " -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 " sudo sed -e "
s|%PUBLICPORT%|$heat_cw_api_port|g; s|%PUBLICPORT%|$heat_cw_api_port|g;
s|%APACHE_NAME%|$APACHE_NAME|g; s|%APACHE_NAME%|$APACHE_NAME|g;

View File

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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

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

View File

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

View File

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