summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJenkins <jenkins@review.openstack.org>2017-06-19 21:41:13 +0000
committerGerrit Code Review <review@openstack.org>2017-06-19 21:41:13 +0000
commit0325eaf2aca99f284c523a5769a3fc901908151b (patch)
treed7fc5db32c323d564c5cb40e21a945ed2a66abb0
parent6255254d65c173a55580d74539532060f6722b80 (diff)
parent623492cc212f29df63b8af54d1347c9561d247d5 (diff)
Merge "Add docs and sample configs for running glance with apache"
-rw-r--r--doc/source/apache-httpd.rst93
-rw-r--r--doc/source/index.rst1
-rw-r--r--httpd/README2
-rw-r--r--httpd/glance-api-uwsgi.ini17
-rw-r--r--httpd/uwsgi-glance-api.conf2
5 files changed, 115 insertions, 0 deletions
diff --git a/doc/source/apache-httpd.rst b/doc/source/apache-httpd.rst
new file mode 100644
index 0000000..ec8ef3a
--- /dev/null
+++ b/doc/source/apache-httpd.rst
@@ -0,0 +1,93 @@
1=======================
2Running Glance in HTTPD
3=======================
4
5Since the Pike release Glance has packaged a wsgi script entrypoint that
6enables you to run it with a real web server like Apache HTTPD or nginx. To
7deploy this there are several patterns. This doc shows two common ways of
8deploying Glance with Apache HTTPD.
9
10uwsgi
11-----
12
13This is the current recommended way to deploy Glance with a real web server.
14In this deployment method we use uwsgi as a web server bound to a random local
15port. Then we configure apache using mod_proxy to forward all incoming requests
16on the specified endpoint to that local webserver. This has the advantage of
17letting apache manage all inbound http connections, but letting uwsgi manage
18running the python code. It also means when we make changes to Glance code
19or configuration we don't need to restart all of apache (which may be running
20other services too) and just need to restart the local uwsgi daemon.
21
22The httpd/ directory contains sample files for configuring HTTPD to run Glance
23under uwsgi in this configuration. To use the sample configs simply copy
24`httpd/uwsgi-glance-api.conf` to the appropriate location for your Apache
25server. On Debian/Ubuntu systems it is::
26
27 /etc/apache2/sites-available/uwsgi-glance-api.conf
28
29On Red Hat based systems it is::
30
31 /etc/httpd/conf.d/uwsgi-glance-api.conf
32
33Enable mod_proxy by running ``sudo a2enmod proxy``
34
35Then on Ubuntu/Debian systems enable the site by creating a symlink from the
36file in ``sites-available`` to ``sites-enabled``. (This is not required on Red
37Hat based systems)::
38
39 ln -s /etc/apache2/sites-available/uwsgi-glance-api.conf /etc/apache2/sites-enabled
40
41Start or restart HTTPD to pick up the new configuration.
42
43Now we need to configure and start the uwsgi service. Copy the
44`httpd/glance-api-uwsgi.ini` file to `/etc/glance`. Update the file to match
45your system configuration (for example, you'll want to set the number of
46processes and threads).
47
48Install uwsgi and start the glance-api server using uwsgi::
49
50 sudo pip install uwsgi
51 uwsgi --ini /etc/glance/glance-api-uwsgi.ini
52
53.. NOTE::
54
55 In the sample configs port 60999 is used, but this doesn't matter and is
56 just a randomly selected number. This is not a contract on the port used
57 for the local uwsgi daemon.
58
59
60mod_proxy_uwsgi
61'''''''''''''''
62
63.. WARNING::
64
65 Running Glance under HTTPD in this configuration will only work on Python 2
66 if you use ``Transfer-Encoding: chunked``. Also if running with Python 2
67 apache will be buffering the chunked encoding before passing the request
68 on to uwsgi. See bug: https://github.com/unbit/uwsgi/issues/1540
69
70Instead of running uwsgi as a webserver listening on a local port and then
71having Apache HTTP proxy all the incoming requests with mod_proxy. The
72normally recommended way of deploying uwsgi with Apache HTTPD is to use
73mod_proxy_uwsgi and set up a local socket file for uwsgi to listen on. Apache
74will send the requests using the uwsgi protocol over this local socket
75file. However, there are issues with doing this and using chunked-encoding.
76
77You can work around these issues by configuring your apache proxy to buffer the
78chunked data and send the full content length to uwsgi. You do this by adding::
79
80 SetEnv proxy-sendcl 1
81
82to the apache config file using mod_proxy_uwsgi. For more details on using
83mod_proxy_uwsgi see the official docs:
84http://uwsgi-docs.readthedocs.io/en/latest/Apache.html?highlight=mod_uwsgi_proxy#mod-proxy-uwsgi
85
86mod_wsgi
87--------
88
89This deployment method is not recommended for using Glance. The mod_wsgi
90protocol does not support ``Transfer-Encoding: chunked`` and therefore makes it
91unsuitable for use with Glance. However, you could theoretically deploy Glance
92using mod_wsgi but it will fail on any requests that use a chunked transfer
93encoding.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 13308cf..9c1329e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -105,6 +105,7 @@ Administration guide
105 property-protections 105 property-protections
106 opts/index 106 opts/index
107 requirements 107 requirements
108 apache-httpd
108 109
109Operating Glance 110Operating Glance
110~~~~~~~~~~~~~~~~ 111~~~~~~~~~~~~~~~~
diff --git a/httpd/README b/httpd/README
new file mode 100644
index 0000000..20bf42f
--- /dev/null
+++ b/httpd/README
@@ -0,0 +1,2 @@
1Documentation for running Glance with Apache HTTPD is in
2doc/source/apache-httpd.rst
diff --git a/httpd/glance-api-uwsgi.ini b/httpd/glance-api-uwsgi.ini
new file mode 100644
index 0000000..3b10be8
--- /dev/null
+++ b/httpd/glance-api-uwsgi.ini
@@ -0,0 +1,17 @@
1[uwsgi]
2http-auto-chunked = true
3http-chunked-input = true
4http-raw-body = true
5chmod-socket = 666
6lazy-apps = true
7add-header = Connection: close
8buffer-size = 65535
9thunder-lock = true
10plugins = python
11enable-threads = true
12exit-on-reload = true
13die-on-term = true
14master = true
15processes = 4
16http = 127.0.0.1:60999
17wsgi-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 0000000..84bd7dd
--- /dev/null
+++ b/httpd/uwsgi-glance-api.conf
@@ -0,0 +1,2 @@
1KeepAlive Off
2ProxyPass "/image" "http://127.0.0.1:60999" retry=0