Drop wsgi script, docs around mod_wsgi
Ironic, like most openstack services these days, needs to have it's wsgi module referenced as a module, and used under something like uwsgi or gunicorn instead of with Apache mod_wsgi. Assisted-by: claude code Change-Id: I6a2c2688f73b71f94103622a9e821cab67be053e Signed-off-by: Jay Faulkner <jay@jvf.cc>
This commit is contained in:
Jay Faulkner
@@ -1,94 +0,0 @@
|
||||
Configuring ironic-api behind mod_wsgi
|
||||
--------------------------------------
|
||||
|
||||
Bare Metal service comes with an example file for configuring the
|
||||
``ironic-api`` service to run behind Apache with mod_wsgi.
|
||||
|
||||
.. note::
|
||||
This is optional, the ironic APIs can be run using
|
||||
independent scripts that provide HTTP servers. But it is generally
|
||||
considered more performant and flexible to run them using a generic
|
||||
HTTP server that supports WSGI (such as Apache or nginx).
|
||||
|
||||
#. Install the apache service:
|
||||
|
||||
Fedora/RHEL9/CentOS 9::
|
||||
|
||||
sudo dnf install httpd
|
||||
|
||||
Debian/Ubuntu::
|
||||
|
||||
apt-get install apache2
|
||||
|
||||
#. Download the ``etc/apache2/ironic`` file from the
|
||||
`Ironic project tree <https://opendev.org/openstack/ironic/raw/branch/master/etc/apache2/ironic>`_
|
||||
and copy it to the apache sites:
|
||||
|
||||
Fedora/RHEL9/CentOS 9::
|
||||
|
||||
sudo cp etc/apache2/ironic /etc/httpd/conf.d/ironic.conf
|
||||
|
||||
Debian/Ubuntu::
|
||||
|
||||
sudo cp etc/apache2/ironic /etc/apache2/sites-available/ironic.conf
|
||||
|
||||
#. Edit the recently copied ``<apache-configuration-dir>/ironic.conf``:
|
||||
|
||||
#. Modify the ``WSGIDaemonProcess``, ``APACHE_RUN_USER`` and
|
||||
``APACHE_RUN_GROUP`` directives to set the user and group values to
|
||||
an appropriate user on your server.
|
||||
|
||||
#. Modify the ``WSGIScriptAlias`` directive to point to the automatically
|
||||
generated ``ironic-api-wsgi`` script that is located in `IRONIC_BIN`
|
||||
directory.
|
||||
|
||||
#. Modify the ``Directory`` directive to set the path to the Ironic API code.
|
||||
|
||||
#. Modify the ``ErrorLog`` and ``CustomLog`` to redirect the logs
|
||||
to the right directory (on Red Hat systems this is usually under
|
||||
/var/log/httpd).
|
||||
|
||||
#. Stop and disable the ironic-api service. If ironic-api service is
|
||||
started, the port will be occupied. Apache will fail to start:
|
||||
|
||||
Fedora/RHEL9/CentOS 9::
|
||||
|
||||
sudo systemctl stop openstack-ironic-api
|
||||
sudo systemctl disable openstack-ironic-api
|
||||
|
||||
Debian/Ubuntu::
|
||||
|
||||
sudo service ironic-api stop
|
||||
sudo service ironic-api disable
|
||||
|
||||
#. Enable the apache ``ironic`` in site and reload:
|
||||
|
||||
Fedora/RHEL9/CentOS 9::
|
||||
|
||||
sudo systemctl reload httpd
|
||||
|
||||
Debian/Ubuntu::
|
||||
|
||||
sudo a2ensite ironic
|
||||
sudo service apache2 reload
|
||||
|
||||
.. note::
|
||||
The file ``ironic-api-wsgi`` is automatically generated by pbr and is
|
||||
available in `IRONIC_BIN` directory. It should not be modified.
|
||||
|
||||
Configure another WSGI container
|
||||
--------------------------------
|
||||
|
||||
A slightly different approach has to be used for WSGI containers that cannot
|
||||
use ``ironic-api-wsgi``. For example, for *gunicorn*:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
gunicorn -b 0.0.0.0:6385 'ironic.api.wsgi:initialize_wsgi_app(argv=[])'
|
||||
|
||||
If you want to pass a configuration file, use:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
gunicorn -b 0.0.0.0:6385 \
|
||||
'ironic.api.wsgi:initialize_wsgi_app(argv=["ironic-api", "--config-file=/path/to/_ironic.conf"])'
|
||||
116
doc/source/install/include/configure-ironic-api-wsgi.inc
Normal file
116
doc/source/install/include/configure-ironic-api-wsgi.inc
Normal file
@@ -0,0 +1,116 @@
|
||||
Configuring ironic-api behind a WSGI server
|
||||
--------------------------------------------
|
||||
|
||||
Bare Metal service can be configured to run behind any WSGI-capable
|
||||
web server like uWSGI or Gunicorn for better performance and scalability.
|
||||
|
||||
.. note::
|
||||
This is optional, the ironic APIs can be run using
|
||||
the standalone ``ironic-api`` command. However, for production deployments,
|
||||
it is recommended to use a proper WSGI server for better performance,
|
||||
multiple workers, and integration with existing infrastructure.
|
||||
|
||||
The WSGI application
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Ironic provides a WSGI application at ``ironic.wsgi:application`` that can
|
||||
be used with any WSGI server. The below example uses uWSGI, which is used in
|
||||
Ironic CI jobs.
|
||||
|
||||
Using uWSGI
|
||||
~~~~~~~~~~~
|
||||
|
||||
#. Install uWSGI::
|
||||
|
||||
pip install uwsgi
|
||||
|
||||
#. Create a uWSGI configuration file (e.g., ``/etc/uwsgi/ironic.ini``)::
|
||||
|
||||
[uwsgi]
|
||||
module = ironic.wsgi:application
|
||||
http-socket = 127.0.0.1:6385
|
||||
processes = 2
|
||||
; allow 60 seconds for graceful shutdown on SIGTERM
|
||||
die-on-term = true
|
||||
exit-on-reload = false
|
||||
hook-master-start = unix_signal:15 gracefully_kill_them_all
|
||||
worker-reload-mercy = 60
|
||||
; disallow connection reuse
|
||||
add-header = Connection: close
|
||||
; Prevent thundering herd on accept()
|
||||
thunder-lock = true
|
||||
; ensure file descriptors aren't shared between processes
|
||||
lazy-apps = true
|
||||
enable-threads = true
|
||||
master = true
|
||||
|
||||
.. note::
|
||||
This uWSGI configuration and comments are based on devstack configuration.
|
||||
You may need to modify settings depending on your deployment method and
|
||||
scale.
|
||||
|
||||
|
||||
#. Start uWSGI::
|
||||
|
||||
uwsgi --ini /etc/uwsgi/ironic.ini
|
||||
|
||||
Reverse Proxy Configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
WSGI servers are typically deployed behind a reverse proxy like nginx or
|
||||
Apache for SSL termination, load balancing, and serving static files.
|
||||
|
||||
Example nginx configuration::
|
||||
|
||||
upstream ironic-api {
|
||||
server 127.0.0.1:6385;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name ironic.example.com;
|
||||
|
||||
ssl_certificate /etc/ssl/certs/ironic.crt;
|
||||
ssl_certificate_key /etc/ssl/private/ironic.key;
|
||||
|
||||
location / {
|
||||
proxy_pass http://ironic-api;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
|
||||
For detailed reverse proxy configurations, see:
|
||||
|
||||
* `nginx documentation <https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/>`_
|
||||
* `Apache mod_proxy documentation <https://httpd.apache.org/docs/current/mod/mod_proxy.html>`_
|
||||
* `HAProxy documentation <https://www.haproxy.org/download/2.4/doc/configuration.txt>`_
|
||||
|
||||
Passing Configuration Options
|
||||
------------------------------
|
||||
|
||||
By default, Ironic will use its standard configuration file search paths.
|
||||
If you need to specify a custom configuration file:
|
||||
|
||||
For the initialization method with arguments::
|
||||
|
||||
# uWSGI with custom config (in ini file)
|
||||
[uwsgi]
|
||||
module = ironic.api.wsgi:initialize_wsgi_app(argv=["--config-file=/etc/ironic/ironic.conf"])
|
||||
|
||||
Alternatively, you can set environment variables before starting the WSGI server::
|
||||
|
||||
export OS_CLOUD=mycloud
|
||||
# or
|
||||
export IRONIC_CONF=/etc/ironic/ironic.conf
|
||||
|
||||
Important Considerations
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
#. Stop and disable the standalone ironic-api service before starting
|
||||
the WSGI server to avoid port conflicts.
|
||||
|
||||
#. When behind a reverse proxy, ensure ``[oslo_middleware]/enable_proxy_headers_parsing``
|
||||
is set to ``True`` in ironic.conf to properly handle X-Forwarded headers.
|
||||
@@ -58,7 +58,7 @@ On Ubuntu_/Debian:
|
||||
|
||||
.. include:: include/configure-ironic-api.inc
|
||||
|
||||
.. include:: include/configure-ironic-api-mod_wsgi.inc
|
||||
.. include:: include/configure-ironic-api-wsgi.inc
|
||||
|
||||
.. include:: include/configure-ironic-conductor.inc
|
||||
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
# Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
# not use this file except in compliance with the License. You may obtain
|
||||
# a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
# This is an example Apache2 configuration file for using the
|
||||
# Ironic API through mod_wsgi. This version assumes you are
|
||||
# running devstack to configure the software, and PBR has generated
|
||||
# and installed the ironic-api-wsgi script while installing ironic.
|
||||
|
||||
Listen 6385
|
||||
|
||||
<VirtualHost *:6385>
|
||||
WSGIDaemonProcess ironic user=stack group=stack threads=10 display-name=%{GROUP}
|
||||
WSGIScriptAlias / /usr/local/bin/ironic-api-wsgi
|
||||
|
||||
SetEnv APACHE_RUN_USER stack
|
||||
SetEnv APACHE_RUN_GROUP stack
|
||||
WSGIProcessGroup ironic
|
||||
|
||||
ErrorLog /var/log/apache2/ironic_error.log
|
||||
LogLevel info
|
||||
CustomLog /var/log/apache2/ironic_access.log combined
|
||||
|
||||
<Directory /opt/stack/ironic/ironic/api>
|
||||
WSGIProcessGroup ironic
|
||||
WSGIApplicationGroup %{GLOBAL}
|
||||
AllowOverride All
|
||||
Require all granted
|
||||
</Directory>
|
||||
</VirtualHost>
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
upgrade:
|
||||
- |
|
||||
The ``wsgi_scripts`` entry point ``ironic-api-wsgi`` has been removed
|
||||
from ``setup.cfg``. WSGI servers should now use the module path
|
||||
``ironic.wsgi:application`` directly instead of the generated script.
|
||||
This change aligns with the OpenStack goal to migrate from WSGI scripts
|
||||
to module paths and is compatible with modern Python packaging tools.
|
||||
|
||||
For example, with gunicorn::
|
||||
|
||||
gunicorn ironic.wsgi:application
|
||||
|
||||
Or with uwsgi::
|
||||
|
||||
[uwsgi]
|
||||
module = ironic.wsgi:application
|
||||
- |
|
||||
The Apache mod_wsgi sample configuration has been removed. Operators
|
||||
should use modern WSGI servers like uWSGI or Gunicorn instead, which
|
||||
provide better performance and are simpler to configure. See the
|
||||
updated deployment documentation for examples.
|
||||
deprecations:
|
||||
- |
|
||||
While the legacy ``ironic.api.wsgi:initialize_wsgi_app()`` function
|
||||
remains available for backward compatibility, new deployments should
|
||||
use ``ironic.wsgi:application`` instead.
|
||||
@@ -48,9 +48,6 @@ console_scripts =
|
||||
ironic-status = ironic.command.status:main
|
||||
ironic-pxe-filter = ironic.command.pxe_filter:main
|
||||
|
||||
wsgi_scripts =
|
||||
ironic-api-wsgi = ironic.api.wsgi:initialize_wsgi_app
|
||||
|
||||
ironic.dhcp =
|
||||
dnsmasq = ironic.dhcp.dnsmasq:DnsmasqDHCPApi
|
||||
neutron = ironic.dhcp.neutron:NeutronDHCPApi
|
||||
|
||||
Reference in New Issue
Block a user