From 623492cc212f29df63b8af54d1347c9561d247d5 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Wed, 24 May 2017 02:00:11 -0400 Subject: [PATCH] Add docs and sample configs for running glance with apache This commit adds docs and sample configs to glance for running glance under apache. It also documents the limitations with the 2 common methods of deploying wsgi scripts with apache, mod_wsgi and mod_proxy_uwsgi, and why those don't work for the glance use case. Change-Id: I856e7ada856128def48deda5b063d818f45af336 --- doc/source/apache-httpd.rst | 93 +++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + httpd/README | 2 + httpd/glance-api-uwsgi.ini | 17 +++++++ httpd/uwsgi-glance-api.conf | 2 + 5 files changed, 115 insertions(+) create mode 100644 doc/source/apache-httpd.rst create mode 100644 httpd/README create mode 100644 httpd/glance-api-uwsgi.ini create mode 100644 httpd/uwsgi-glance-api.conf diff --git a/doc/source/apache-httpd.rst b/doc/source/apache-httpd.rst new file mode 100644 index 0000000000..ec8ef3a685 --- /dev/null +++ b/doc/source/apache-httpd.rst @@ -0,0 +1,93 @@ +======================= +Running Glance in HTTPD +======================= + +Since the Pike release Glance has packaged a wsgi script entrypoint that +enables you to run it with a real web server like Apache HTTPD or nginx. To +deploy this there are several patterns. This doc shows two common ways of +deploying Glance with Apache HTTPD. + +uwsgi +----- + +This is the current recommended way to deploy Glance with a real web server. +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, but letting uwsgi manage +running the python code. It also means when we make changes to Glance 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 daemon. + +The httpd/ directory contains sample files for configuring HTTPD to run Glance +under uwsgi in this configuration. To use the sample configs simply copy +`httpd/uwsgi-glance-api.conf` to the appropriate location for your Apache +server. On Debian/Ubuntu systems it is:: + + /etc/apache2/sites-available/uwsgi-glance-api.conf + +On Red Hat based systems it is:: + + /etc/httpd/conf.d/uwsgi-glance-api.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-glance-api.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 +`httpd/glance-api-uwsgi.ini` file to `/etc/glance`. Update the file to match +your system configuration (for example, you'll want to set the number of +processes and threads). + +Install uwsgi and start the glance-api server using uwsgi:: + + sudo pip install uwsgi + uwsgi --ini /etc/glance/glance-api-uwsgi.ini + +.. NOTE:: + + In the sample configs port 60999 is 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 +''''''''''''''' + +.. WARNING:: + + Running Glance under HTTPD in this configuration will only work on Python 2 + if you use ``Transfer-Encoding: chunked``. Also if running with Python 2 + apache will be buffering the chunked encoding before passing the request + on to uwsgi. See bug: https://github.com/unbit/uwsgi/issues/1540 + +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. However, there are issues with doing this and using chunked-encoding. + +You can work around these issues by configuring your apache proxy to buffer the +chunked data and send the full content length to uwsgi. You do this by adding:: + + SetEnv proxy-sendcl 1 + +to the apache config file using mod_proxy_uwsgi. 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 + +mod_wsgi +-------- + +This deployment method is not recommended for using Glance. The mod_wsgi +protocol does not support ``Transfer-Encoding: chunked`` and therefore makes it +unsuitable for use with Glance. However, you could theoretically deploy Glance +using mod_wsgi but it will fail on any requests that use a chunked transfer +encoding. diff --git a/doc/source/index.rst b/doc/source/index.rst index 13308cf1e8..9c1329e742 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -105,6 +105,7 @@ Administration guide property-protections opts/index requirements + apache-httpd Operating Glance ~~~~~~~~~~~~~~~~ diff --git a/httpd/README b/httpd/README new file mode 100644 index 0000000000..20bf42f835 --- /dev/null +++ b/httpd/README @@ -0,0 +1,2 @@ +Documentation for running Glance with Apache HTTPD is in +doc/source/apache-httpd.rst diff --git a/httpd/glance-api-uwsgi.ini b/httpd/glance-api-uwsgi.ini new file mode 100644 index 0000000000..3b10be8e02 --- /dev/null +++ b/httpd/glance-api-uwsgi.ini @@ -0,0 +1,17 @@ +[uwsgi] +http-auto-chunked = true +http-chunked-input = true +http-raw-body = true +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:60999 +wsgi-file = /usr/local/bin/glance-wsgi-api diff --git a/httpd/uwsgi-glance-api.conf b/httpd/uwsgi-glance-api.conf new file mode 100644 index 0000000000..84bd7dd8c3 --- /dev/null +++ b/httpd/uwsgi-glance-api.conf @@ -0,0 +1,2 @@ +KeepAlive Off +ProxyPass "/image" "http://127.0.0.1:60999" retry=0