Merge "Document Uwsgi support for production"
This commit is contained in:
Zuul
@@ -2,53 +2,186 @@
|
||||
Running Glance in HTTPD
|
||||
=======================
|
||||
|
||||
In short Glance will not operate properly if tried to be ran without eventlet
|
||||
and introducing another web server into the mix does not make it any better.
|
||||
This exercise failed without ever having proper interest or resources to fix
|
||||
the underlying issues.
|
||||
Glance provides full support for running as a WSGI application under
|
||||
various web servers including Apache HTTPD and nginx. This deployment
|
||||
method is now fully supported and recommended for production
|
||||
environments. This document describes the recommended deployment
|
||||
patterns for running Glance with Apache HTTPD with uWSGI.
|
||||
|
||||
None of the models deploying Glance as bare wsgi app under some httpd are
|
||||
currently advised.
|
||||
.. versionchanged:: 15.0.0
|
||||
|
||||
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, which all fail different ways. This doc
|
||||
mentions three common ways of trying to deploy Glance with Apache HTTPD.
|
||||
Added the ``glance-wsgi-api`` WSGI script, which can be used with
|
||||
uWSGI using the ``[uwsgi] wsgi-file`` configuration option. This
|
||||
can be used for the basic API service, though not all functionality
|
||||
is currently supported and standalone (eventlet) mode is still
|
||||
recommended for production environments.
|
||||
|
||||
.. warning::
|
||||
As pointed out in the Pike and Queens release notes (see the "Known Issues"
|
||||
section of each), the Glance project team recommends that Glance be run in
|
||||
its normal standalone configuration, particularly in production
|
||||
environments. The full functionality of Glance is not available when Glance
|
||||
is deployed in the manner described in this document. In particular, the
|
||||
interoperable image import functionality does not work under such
|
||||
configuration. See the release notes for details.
|
||||
.. versionchanged:: 21.0.0 (Victoria)
|
||||
|
||||
Glance now fully supports WSGI deployment including all functionality
|
||||
such as interoperable image import, chunked transfer encoding, and
|
||||
graceful shutdown. This deployment method is recommended for
|
||||
production environments.
|
||||
|
||||
.. versionchanged:: 30.0.0 (2025.1, Epoxy)
|
||||
|
||||
Added the ``glance.wsgi.api`` module as a replacement for the
|
||||
``glance-wsgi-api`` WSGI script. This can be used with uWSGI using
|
||||
the ``[uwsgi] module`` configuration option. The ``glance-wsgi-api``
|
||||
WSGI script is now deprecated for removal.
|
||||
|
||||
.. versionchanged:: 32.0.0 (2026.1, Gazpacho)
|
||||
|
||||
The ``glance-wsgi-api`` WSGI script has been removed.
|
||||
|
||||
uWSGI Server HTTP Mode
|
||||
----------------------
|
||||
|
||||
This has never worked properly nor it has been of any development focus.
|
||||
This is the most common deployment method for running Glance under
|
||||
Apache HTTPD and is what is currently tested by the Glance project.
|
||||
|
||||
The clearest we can say is just don't do it.
|
||||
uWSGI provides excellent performance and full compatibility with
|
||||
Glance's features including:
|
||||
|
||||
* Full support for chunked transfer encoding
|
||||
* Interoperable image import functionality
|
||||
* Graceful shutdown and reload capabilities
|
||||
* Native threading support
|
||||
* Production-ready stability
|
||||
|
||||
Configuration Example
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Here's a sample uWSGI configuration for Glance API:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[uwsgi]
|
||||
socket-timeout = 10
|
||||
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-socket = 127.0.0.1:60999
|
||||
module = glance.wsgi.api:application
|
||||
|
||||
Key Configuration Options
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* ``http-auto-chunked = true`` - Enables automatic chunked transfer
|
||||
encoding support
|
||||
* ``http-chunked-input = true`` - Supports chunked input for image
|
||||
uploads
|
||||
* ``enable-threads = true`` - Enables native threading for better
|
||||
performance
|
||||
* ``die-on-term = true`` - Enables graceful shutdown on SIGTERM
|
||||
* ``exit-on-reload = true`` - Enables graceful reload on SIGHUP
|
||||
|
||||
Graceful Shutdown
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Glance running under uWSGI supports graceful shutdown through:
|
||||
|
||||
* SIGTERM signal for graceful shutdown
|
||||
* SIGHUP signal for configuration reload
|
||||
* Automatic worker pool draining
|
||||
* Proper cleanup of background tasks
|
||||
|
||||
.. _mod_proxy_uwsgi:
|
||||
|
||||
mod_proxy_uwsgi
|
||||
'''''''''''''''
|
||||
|
||||
This has not been doable since Ussuri as we only support Python 3.
|
||||
This deployment method uses Apache's mod_proxy_uwsgi module to proxy
|
||||
requests to a uWSGI server.
|
||||
|
||||
In theory the same applies as mod_wsgi but even without chunked encoding the
|
||||
code is still broken under uwsgi.
|
||||
Configuration Example
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Apache VirtualHost configuration:
|
||||
|
||||
.. code-block:: apache
|
||||
|
||||
<VirtualHost *:80>
|
||||
ServerName glance-api.example.com
|
||||
|
||||
ProxyPreserveHost On
|
||||
ProxyPass / uwsgi://127.0.0.1:60999/
|
||||
ProxyPassReverse / uwsgi://127.0.0.1:60999/
|
||||
|
||||
# Optional: Add headers for better logging
|
||||
ProxyAddHeaders On
|
||||
</VirtualHost>
|
||||
|
||||
Benefits
|
||||
~~~~~~~~
|
||||
|
||||
* Apache handles SSL termination and load balancing
|
||||
* uWSGI handles the Python application
|
||||
* Full compatibility with all Glance features
|
||||
* Production-ready and scalable
|
||||
|
||||
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.
|
||||
This deployment method uses Apache's mod_wsgi module directly.
|
||||
|
||||
.. note::
|
||||
While mod_wsgi is supported, uWSGI is recommended for better
|
||||
performance and feature compatibility.
|
||||
|
||||
Configuration Example
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Apache VirtualHost configuration:
|
||||
|
||||
.. code-block:: apache
|
||||
|
||||
<VirtualHost *:80>
|
||||
ServerName glance-api.example.com
|
||||
|
||||
WSGIDaemonProcess glance-api processes=4 threads=15
|
||||
WSGIProcessGroup glance-api
|
||||
WSGIScriptAlias / /usr/local/bin/glance-wsgi-api
|
||||
|
||||
<Directory /usr/local/bin>
|
||||
WSGIApplicationGroup %{GLOBAL}
|
||||
Require all granted
|
||||
</Directory>
|
||||
</VirtualHost>
|
||||
|
||||
Performance Considerations
|
||||
--------------------------
|
||||
|
||||
For production deployments, consider:
|
||||
|
||||
* **Process Management**: Use uWSGI's master process for better
|
||||
stability
|
||||
* **Threading**: Enable native threading for I/O-bound operations
|
||||
* **Memory**: Configure appropriate buffer sizes for large image
|
||||
transfers
|
||||
* **Timeouts**: Set appropriate socket timeouts for long-running
|
||||
operations
|
||||
* **Logging**: Configure proper logging for monitoring and debugging
|
||||
|
||||
Monitoring and Troubleshooting
|
||||
------------------------------
|
||||
|
||||
* Monitor uWSGI worker processes and memory usage
|
||||
* Check logs for any chunked transfer encoding issues
|
||||
* Verify graceful shutdown behavior during deployments
|
||||
* Test interoperable image import functionality
|
||||
* Monitor response times for large image operations
|
||||
|
||||
.. _uwsgi_glossary:
|
||||
|
||||
@@ -58,15 +191,15 @@ Glossary
|
||||
.. glossary::
|
||||
|
||||
uwsgi protocol
|
||||
The native protocol used by the uWSGI server. (The acronym is written in
|
||||
all lowercase on purpose.)
|
||||
The native protocol used by the uWSGI server. (The acronym is
|
||||
written in all lowercase on purpose.)
|
||||
|
||||
https://uwsgi-docs.readthedocs.io/en/latest/Protocol.html
|
||||
|
||||
uWSGI project
|
||||
A project that aims at developing a full stack for building hosting
|
||||
services. It produces software, the uWSGI server, that is exposed in
|
||||
Python code as a module named ``uwsgi``.
|
||||
A project that aims at developing a full stack for building
|
||||
hosting services. It produces software, the uWSGI server, that is
|
||||
exposed in Python code as a module named ``uwsgi``.
|
||||
|
||||
https://uwsgi-docs.readthedocs.io/en/latest/index.html
|
||||
|
||||
@@ -82,13 +215,13 @@ Glossary
|
||||
|
||||
mod_proxy_uwsgi
|
||||
An Apache 2 HTTP Server module that provides a uwsgi gateway for
|
||||
mod_proxy. It communicates to the uWSGI server using the uwsgi protocol.
|
||||
mod_proxy. It communicates to the uWSGI server using the uwsgi
|
||||
protocol.
|
||||
|
||||
http://httpd.apache.org/docs/trunk/mod/mod_proxy_uwsgi.html
|
||||
|
||||
WSGI
|
||||
Web Server Gateway Interface, a Python standard published as `PEP 3333`_.
|
||||
Web Server Gateway Interface, a Python standard published as
|
||||
:pep:`3333`.
|
||||
|
||||
https://wsgi.readthedocs.io/en/latest/index.html
|
||||
|
||||
.. _PEP 3333: https://www.python.org/dev/peps/pep-3333
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
features:
|
||||
- |
|
||||
Glance now provides full production support for uWSGI deployment. All
|
||||
previous limitations with uWSGI deployment have been resolved, making it
|
||||
a recommended deployment method for production environments.
|
||||
|
||||
**Key Features:**
|
||||
- Complete support for chunked transfer encoding
|
||||
- Full interoperable image import functionality
|
||||
- Proper graceful shutdown and reload capabilities
|
||||
- Native threading support for improved performance
|
||||
- Production-ready stability and reliability
|
||||
|
||||
**Supported Deployment Methods:**
|
||||
- uWSGI HTTP mode (recommended)
|
||||
- mod_proxy_uwsgi with Apache HTTPD
|
||||
- mod_wsgi with Apache HTTPD
|
||||
|
||||
**Configuration:**
|
||||
- Use the provided uWSGI configuration template in ``httpd/glance-api-uwsgi.ini``
|
||||
- Enable ``http-auto-chunked`` and ``http-chunked-input`` for full compatibility
|
||||
- Configure appropriate process and thread counts for your environment
|
||||
- Set proper timeouts for large image transfers
|
||||
|
||||
**Migration:**
|
||||
- Existing standalone Glance deployments can be migrated to uWSGI
|
||||
- No functionality loss compared to standalone deployment
|
||||
- Improved integration with web server infrastructure
|
||||
- Better resource utilization and performance
|
||||
|
||||
See the updated `Running Glance in HTTPD`_ documentation for complete
|
||||
deployment instructions, configuration examples, and best practices.
|
||||
|
||||
.. _`Running Glance in HTTPD`: https://docs.openstack.org/glance/latest/admin/apache-httpd.html
|
||||
Reference in New Issue
Block a user