From 3db454f0ead9ca791063cfdd210d0fd2d62885bf Mon Sep 17 00:00:00 2001
From: Jay Faulkner <jay@jvf.cc>
Date: Fri, 30 Aug 2024 10:49:38 -0700
Subject: [PATCH] Enable WSGI module entrypoint for Ironic

This adds a wsgi entrypoint module which can be used with a wsgi runner,
such as uwsgi, to launch Ironic API processes without the need of a
separate script.

The legacy WSGI script is currently being installed by PBR, and as part
of the migration to a pyproject.yaml-compatible PBR, we cannot use the
wsgi-scripts plugin anymore, and will be removing the script installed
by it in a future Ironic release.

The new WSGI script, because it has statements at the module top-level,
cannot be autodocumented; we now exclude it.

Also we don't treat all warnings as errors in pdf docs builds to allow
the use of mock autosummary, starting with including the wsgi module.

Co-Authored-By: Doug Goldstein <cardoe@cardoe.com>
Change-Id: I584ac6a25c4e6cd9744a609b50d12b434a930dc6
---
 devstack/lib/ironic                           |  4 ++--
 doc/source/conf.py                            |  8 ++++++-
 ironic/wsgi/__init__.py                       | 23 +++++++++++++++++++
 ...add-wsgi-entrypoints-79f8f3cf3b7a663f.yaml | 18 +++++++++++++++
 tox.ini                                       |  2 +-
 5 files changed, 51 insertions(+), 4 deletions(-)
 create mode 100644 ironic/wsgi/__init__.py
 create mode 100644 releasenotes/notes/add-wsgi-entrypoints-79f8f3cf3b7a663f.yaml

diff --git a/devstack/lib/ironic b/devstack/lib/ironic
index 09cb8fc80a..e0946afdc7 100644
--- a/devstack/lib/ironic
+++ b/devstack/lib/ironic
@@ -411,7 +411,7 @@ fi
 # Support entry points installation of console scripts
 IRONIC_BIN_DIR=$(get_python_exec_prefix)
 IRONIC_UWSGI_CONF=$IRONIC_CONF_DIR/ironic-uwsgi.ini
-IRONIC_UWSGI=$IRONIC_BIN_DIR/ironic-api-wsgi
+IRONIC_UWSGI=${IRONIC_UWSGI:-ironic.wsgi:application}
 
 # Lets support IPv6 testing!
 IRONIC_IP_VERSION=${IRONIC_IP_VERSION:-${IP_VERSION:-4}}
@@ -1663,7 +1663,7 @@ function configure_ironic {
     fi
 
     # Adds uWSGI for Ironic API
-    write_uwsgi_config "$IRONIC_UWSGI_CONF" "$IRONIC_UWSGI" "/baremetal"
+    write_uwsgi_config "$IRONIC_UWSGI_CONF" "$IRONIC_UWSGI" "/baremetal" "" "ironic-api"
 
     if [[ "$os_VENDOR" =~ (Debian|Ubuntu) ]]; then
         # The groups change with newer libvirt. Older Ubuntu used
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 6d8cdfe84c..0ff75f4722 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -32,7 +32,9 @@ sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts'))
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.viewcode',
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.autosummary',
+              'sphinx.ext.viewcode',
               'sphinx.ext.graphviz',
               'sphinxcontrib.apidoc',
               'sphinxcontrib.rsvgconverter',
@@ -62,6 +64,10 @@ autodoc_default_options = {
     'special-members': '__call__',
 }
 
+autosummary_mock_imports = [
+    'ironic.wsgi',
+]
+
 redfish_interop_source = \
     '../../redfish-interop-profiles/OpenStackIronicProfile.v1_1_0.json'
 redfish_interop_output_dir = 'admin/drivers/redfish/'
diff --git a/ironic/wsgi/__init__.py b/ironic/wsgi/__init__.py
new file mode 100644
index 0000000000..9abb4c02f0
--- /dev/null
+++ b/ironic/wsgi/__init__.py
@@ -0,0 +1,23 @@
+# 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.
+
+"""WSGI application entry-point for Ironic API."""
+
+import threading
+
+from ironic.api import wsgi
+
+application = None
+lock = threading.Lock()
+with lock:
+    if application is None:
+        application = wsgi.initialize_wsgi_app()
diff --git a/releasenotes/notes/add-wsgi-entrypoints-79f8f3cf3b7a663f.yaml b/releasenotes/notes/add-wsgi-entrypoints-79f8f3cf3b7a663f.yaml
new file mode 100644
index 0000000000..90038b8837
--- /dev/null
+++ b/releasenotes/notes/add-wsgi-entrypoints-79f8f3cf3b7a663f.yaml
@@ -0,0 +1,18 @@
+features:
+  - |
+    A new module, ``ironic.wsgi`` has been enabled as an entrypoint for WSGI
+    runners. For example, if using uWSGI then now instead of:
+
+    .. code-block:: ini
+
+        [uwsgi]
+        wsgi-file = /bin/ironic-api-wsgi
+
+    You can now use:
+
+    .. code-block:: ini
+
+        [uwsgi]
+        module = ironic.wsgi:application
+
+    Legacy installed wsgi scripts will be removed in a future version of Ironic.
diff --git a/tox.ini b/tox.ini
index 517c4cd7c4..44d567aeb5 100644
--- a/tox.ini
+++ b/tox.ini
@@ -100,7 +100,7 @@ commands = sphinx-build -b html doc/source doc/build/html
 allowlist_externals = make
 deps = {[testenv:docs]deps}
 commands =
-  sphinx-build -W -b latex doc/source doc/build/pdf
+  sphinx-build -b latex doc/source doc/build/pdf
   make -C doc/build/pdf