Add opt-in SPICE support for Rocky via COPR.

RHEL9 dropped SPICE support from qemu-kvm, and Rocky Linux followed
suit. Up until now the documented guidance has been to use the Debian
or Ubuntu container images if you want to serve the ``spice-direct``
console type, because the stock Rocky nova-libvirt image will simply
fail to start any SPICE-enabled instance.

This change adds a second version of the nova-libvirt container image
called nova-libvirt-spice. It is always built, but is identical for
all supported container base distributions except for Rocky Linux.
In the Rocky Linux case, this container adds the community
maintained ligenix/enterprise-qemu-spice COPR repository that provides
a rebuild of ``qemu-kvm`` with SPICE support re-enabled for both
EPEL 9 and EPEL 10.

Which nova-libvirt container should be used in a given deployment is
delegated to logic in kolla-ansible, based on the deployer's settings
in globals.yml.

The COPR is a third-party rebuild with no vendor support contract.
The release note and support matrix are updated to describe the
opt-in path and call this caveat out explicitly. The earlier
"you must use Debian or Ubuntu" wording in the support matrix is
softened here, rather than by retroactively editing the kerbside
container-build patch that introduced it, so that this feature can
land (or not land) independently of the earlier change.

Partial-Bug: #2131793 (spice-direct consoles)

Prompt: I am interested in seeing how we would go about using
https://copr.fedorainfracloud.org/coprs/ligenix/enterprise-qemu-spice/
to add SPICE support back to the Kolla build Rocky Linux containers
as a new patch in the kolla/ORDER list. Could you please investigate
options here?

Assisted-By: Claude Code
Co-Authored-By: Claude Opus 4.7 (1M context, medium effort) <noreply@anthropic.com>

Change-Id: I410b87b7f8cdd541c48d9a749b3fea634a5f4e6c
Signed-off-by: Michael Still <mikal@stillhq.com>

5 files changed, 176 insertions, 5 deletions

diff --git a/doc/source/support_matrix.rst b/doc/source/support_matrix.rst
index bec1aa0bd..c14c71954 100644
--- a/doc/source/support_matrix.rst
+++ b/doc/source/support_matrix.rst
@@ -110,8 +110,22 @@ For a list of currently unbuildable images please look into
 SPICE limitations
 =================
 
-The new OpenStack Compute console type ``spice-direct`` requires that
-SPICE support be compiled into the qemu running the instance. Sadly,
-Red Hat chose to remove SPICE support from qemu in RHEL9, and Rocky
-Linux has followed along. You therefore _must_ run the Debian or Ubuntu
-container images if you wish to use the ``spice-direct`` console type.
+The OpenStack Compute console type ``spice-direct`` requires that
+SPICE support be compiled into the qemu running the instance. Red Hat
+removed SPICE support from qemu in RHEL9 onwards, and Rocky Linux has
+followed suit, so the stock Rocky Linux container images do not support
+``spice-direct`` out of the box.
+
+As a solution, Kolla builds two copies of the ``nova-libvirt`` container
+regardless of container distribution. These containers are identical on
+other distributions, but for Rocky Linux the community-maintained
+`ligenix/enterprise-qemu-spice
+<https://copr.fedorainfracloud.org/coprs/ligenix/enterprise-qemu-spice/>`__
+COPR repository is installed as it provides a rebuilt ``qemu-kvm``
+with SPICE re-enabled for EPEL 9 and EPEL 10. Because this COPR is a
+third-party rebuild without a vendor support contract, it is recommended
+only for proof-of-concept deployments.
+
+Which container to use for ``nova-libvirt`` is then determined at
+``kolla-ansible deploy`` time based on the value of the ``enable_kerbside``
+flag.
diff --git a/docker/nova/nova-libvirt-spice/Dockerfile.j2 b/docker/nova/nova-libvirt-spice/Dockerfile.j2
new file mode 100644
index 000000000..dd090a1e6
--- /dev/null
+++ b/docker/nova/nova-libvirt-spice/Dockerfile.j2
@@ -0,0 +1,117 @@
+FROM {{ namespace }}/{{ image_prefix }}base:{{ tag }}
+{% block labels %}
+LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}"
+{% endblock %}
+
+{% block nova_libvirt_header %}{% endblock %}
+
+{% import "macros.j2" as macros with context %}
+
+{{ macros.configure_user(name='nova', groups='qemu') }}
+
+{% if base_package_type == 'rpm' %}
+
+    {% set nova_libvirt_extra_repos = ['ceph', 'crb', 'epel', 'openvswitch'] %}
+    {% if base_distro == 'rocky' %}
+        {#
+            The stock Rocky qemu-kvm has SPICE compiled out. To enable
+            Kerbside and the nova ``spice-direct`` console we therefore
+            layer the ligenix COPR in so that qemu-kvm and spice-server
+            are available with SPICE re-enabled. The repo definition
+            lives in kolla/template/repos.yaml so deployers can override
+            it like any other extra repo.
+        #}
+        {% set nova_libvirt_extra_repos = nova_libvirt_extra_repos + ['ligenix-qemu-spice'] %}
+    {% endif %}
+
+{{ macros.enable_extra_repos(nova_libvirt_extra_repos) }}
+
+    {% set nova_libvirt_packages = [
+        'ceph-common',
+        'cyrus-sasl-md5',
+        'cyrus-sasl-scram',
+        'libguestfs',
+        'libvirt-client',
+        'libvirt-daemon',
+        'libvirt-daemon-config-nwfilter',
+        'libvirt-daemon-driver-nwfilter',
+        'libvirt-daemon-driver-nodedev',
+        'openvswitch${KOLLA_RPM_OVS_VERSION}',
+        'qemu-img',
+        'qemu-kvm',
+        'swtpm',
+    ] %}
+    {% if base_arch == 'x86_64' %}
+        {% set nova_libvirt_packages = nova_libvirt_packages + [
+            'edk2-ovmf'
+        ] %}
+    {% elif base_arch == 'aarch64' %}
+        {% set nova_libvirt_packages = nova_libvirt_packages + [
+            'edk2-aarch64'
+        ] %}
+    {% endif %}
+
+    {% if use_ligenix_qemu | default(false) and base_distro == 'rocky' %}
+        {% set nova_libvirt_packages = nova_libvirt_packages + [
+            'qemu-kvm-ui-spice',
+            'spice-server',
+        ] %}
+    {% endif %}
+
+{% elif base_package_type == 'deb' %}
+
+    {% set nova_libvirt_packages = [
+        'ceph-common',
+        'ebtables',
+        'libsasl2-modules-gssapi-mit',
+        'libvirt-clients',
+        'libvirt-daemon-system',
+        'mdevctl',
+        'openvswitch-switch',
+        'pm-utils',
+        'python3-cephfs',
+        'python3-rados',
+        'python3-rbd',
+        'qemu-block-extra',
+        'qemu-system',
+        'qemu-system-modules-spice',
+        'qemu-utils',
+        'sasl2-bin',
+        'swtpm',
+        'swtpm-tools',
+        'tpm2-tools',
+        'trousers'
+    ] %}
+
+    {% if base_arch == "aarch64" %}
+        {% set nova_libvirt_packages = nova_libvirt_packages + [
+            'qemu-efi-aarch64'
+        ] %}
+    {% elif base_arch == "x86_64" %}
+        {% set nova_libvirt_packages = nova_libvirt_packages + [
+            'ovmf',
+        ] %}
+    {% endif %}
+
+    {% if base_distro in ['debian'] %}
+        {% set nova_libvirt_packages = nova_libvirt_packages + [
+            'usermode'
+        ] %}
+    {% endif %}
+{% endif %}
+
+{{ macros.install_packages(nova_libvirt_packages | customizable("packages")) }}
+
+{% if base_package_type == 'deb' %}
+
+RUN rm -f /etc/libvirt/qemu/networks/default.xml /etc/libvirt/qemu/networks/autostart/default.xml
+
+{% endif %}
+
+COPY extend_start.sh /usr/local/bin/kolla_extend_start
+RUN chmod 644 /usr/local/bin/kolla_extend_start
+
+{{ macros.kolla_patch_sources() }}
+
+{% block nova_libvirt_footer %}{% endblock %}
+{% block footer %}{% endblock %}
diff --git a/docker/nova/nova-libvirt-spice/extend_start.sh b/docker/nova/nova-libvirt-spice/extend_start.sh
new file mode 100644
index 000000000..cc41b480b
--- /dev/null
+++ b/docker/nova/nova-libvirt-spice/extend_start.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+if [[ ! -e "/var/log/kolla/libvirt/libvirtd.log" ]]; then
+    mkdir -p /var/log/kolla/libvirt
+    touch /var/log/kolla/libvirt/libvirtd.log
+    chmod 644 /var/log/kolla/libvirt/libvirtd.log
+fi
+if [[ $(stat -c %a /var/log/kolla/libvirt) != "755" ]]; then
+    chmod 755 /var/log/kolla/libvirt
+    chmod 644 /var/log/kolla/libvirt/libvirtd.log
+fi
diff --git a/kolla/template/repos.yaml b/kolla/template/repos.yaml
index f23c18eed..508d82990 100644
--- a/kolla/template/repos.yaml
+++ b/kolla/template/repos.yaml
@@ -140,6 +140,11 @@ rpm:
   hacluster:
     name: "highavailability"
     distro: true
+  ligenix-qemu-spice:
+    baseurl: "https://download.copr.fedorainfracloud.org/results/ligenix/enterprise-qemu-spice/epel-$releasever-$basearch/"
+    gpgkey: "https://download.copr.fedorainfracloud.org/results/ligenix/enterprise-qemu-spice/pubkey.gpg"
+    gpgcheck: 1
+    name: "ligenix-qemu-spice"
   mariadb:
     baseurl: "https://dlm.mariadb.com/repo/mariadb-server/11.4/yum/rhel/$releasever/$basearch"
     gpgkey: "https://downloads.mariadb.com/MariaDB/RPM-GPG-KEY-MariaDB"
diff --git a/releasenotes/notes/rocky-kerbside-spice-copr-9a3f4d7c2b1e8a50.yaml b/releasenotes/notes/rocky-kerbside-spice-copr-9a3f4d7c2b1e8a50.yaml
new file mode 100644
index 000000000..2bb5307ff
--- /dev/null
+++ b/releasenotes/notes/rocky-kerbside-spice-copr-9a3f4d7c2b1e8a50.yaml
@@ -0,0 +1,24 @@
+---
+features:
+  - |
+    Kolla now builds two ``nova-libvirt`` containers: ``nova-libvirt``
+    and ``nova-libvirt-spice``. This second container is used by
+    ``kolla-ansible`` deployments which set ``enable_kerbside: true``
+    in their ``globals.yml``. The two containers are identical, except
+    on Rocky Linux where the community-maintained
+    `ligenix/enterprise-qemu-spice
+    <https://copr.fedorainfracloud.org/coprs/ligenix/enterprise-qemu-spice/>`__
+    COPR repository which rebuilds ``qemu-kvm`` with SPICE support
+    re-enabled is used. The COPR is a third-party rebuild with no vendor
+    support contract and is recommended only for proof-of-concept
+    deployments.
+issues:
+  - |
+    The ligenix/enterprise-qemu-spice COPR builds ship qemu-kvm without
+    the ``usb-audio`` device. Guests configured with
+    ``hw_sound_model=usb`` (the recommended default in the Kerbside
+    ``hw:sound_model`` documentation) will fail to start on Rocky with
+    ``unsupported configuration: usb-audio controller is not supported
+    by this QEMU binary``. Use a different model such as ``ich9`` or
+    ``ac97`` on Rocky deployments until the COPR rebuild ships
+    usb-audio.