Document rolling and release Kolla image tags

docs/appendix/security/ossa-2026-001.md

@@ -109,6 +109,24 @@ that includes the fix. Configure the following in `environments/kolla/images.yml
 keystone_tag: "2024.2"  # or "2025.1", depending on your OpenStack release
 ```
 
+:::warning
+Rolling tags exist only in the `kolla` namespace. In a deployment that uses an OSISM release namespace
+(`docker_namespace: kolla/release/<openstack_version>`), the tag override above resolves to images that do
+not exist and the pull fails with `unknown: artifact ... not found`. Because `keystone_tag` applies to all
+Keystone images, each of them has to be overridden as well, so that they are pulled from the `kolla`
+namespace:
+
+```yaml
+keystone_image: "registry.osism.tech/kolla/keystone"
+keystone_fernet_image: "registry.osism.tech/kolla/keystone-fernet"
+keystone_ssh_image: "registry.osism.tech/kolla/keystone-ssh"
+keystone_httpd_image: "registry.osism.tech/kolla/httpd"
+keystone_tag: "2024.2"  # or "2025.1", depending on your OpenStack release
+```
+
+See [Rolling tags and release tags](../../guides/configuration-guide/openstack/index.md#rolling-tags-and-release-tags).
+:::
+
 ### Mitigation
 
 If you use external OAuth 2.0 authentication, consider the following measures:

docs/appendix/security/ossa-2026-002.md

@@ -92,6 +92,31 @@ that include the fix. Configure the following in `environments/kolla/images.yml`
 nova_tag: "2024.2"  # or "2025.1", depending on your OpenStack release
 ```
 
+:::warning
+Rolling tags exist only in the `kolla` namespace. In a deployment that uses an OSISM release namespace
+(`docker_namespace: kolla/release/<openstack_version>`), the tag override above resolves to images that do
+not exist and the pull fails with `unknown: artifact ... not found`. Because `nova_tag` applies to all Nova
+images, each of them has to be overridden as well, so that they are pulled from the `kolla` namespace:
+
+```yaml
+nova_api_image: "registry.osism.tech/kolla/nova-api"
+nova_compute_image: "registry.osism.tech/kolla/nova-compute"
+nova_compute_ironic_image: "registry.osism.tech/kolla/nova-compute-ironic"
+nova_conductor_image: "registry.osism.tech/kolla/nova-conductor"
+nova_novncproxy_image: "registry.osism.tech/kolla/nova-novncproxy"
+nova_scheduler_image: "registry.osism.tech/kolla/nova-scheduler"
+nova_serialproxy_image: "registry.osism.tech/kolla/nova-serialproxy"
+nova_spicehtml5proxy_image: "registry.osism.tech/kolla/nova-spicehtml5proxy"
+nova_ssh_image: "registry.osism.tech/kolla/nova-ssh"
+nova_super_conductor_image: "registry.osism.tech/kolla/nova-super-conductor"
+nova_tag: "2024.2"  # or "2025.1", depending on your OpenStack release
+```
+
+Only the images actually used in the deployment need to be set. `nova_libvirt_tag` is not derived from
+`nova_tag` and is therefore not affected by this override. See
+[Rolling tags and release tags](../../guides/configuration-guide/openstack/index.md#rolling-tags-and-release-tags).
+:::
+
 ### Mitigation
 
 If you are using the flat image backend with `use_cow_images=False`, consider the following

docs/appendix/security/ossa-2026-005.md

@@ -89,6 +89,24 @@ that includes the fix. Configure the following in `environments/kolla/images.yml
 keystone_tag: "2024.2"  # or "2025.1", depending on your OpenStack release
 ```
 
+:::warning
+Rolling tags exist only in the `kolla` namespace. In a deployment that uses an OSISM release namespace
+(`docker_namespace: kolla/release/<openstack_version>`), the tag override above resolves to images that do
+not exist and the pull fails with `unknown: artifact ... not found`. Because `keystone_tag` applies to all
+Keystone images, each of them has to be overridden as well, so that they are pulled from the `kolla`
+namespace:
+
+```yaml
+keystone_image: "registry.osism.tech/kolla/keystone"
+keystone_fernet_image: "registry.osism.tech/kolla/keystone-fernet"
+keystone_ssh_image: "registry.osism.tech/kolla/keystone-ssh"
+keystone_httpd_image: "registry.osism.tech/kolla/httpd"
+keystone_tag: "2024.2"  # or "2025.1", depending on your OpenStack release
+```
+
+See [Rolling tags and release tags](../../guides/configuration-guide/openstack/index.md#rolling-tags-and-release-tags).
+:::
+
 ### Mitigation
 
 If you are using restricted application credentials with the EC2/S3 API, consider the

docs/appendix/security/ossa-2026-015.md

@@ -154,6 +154,24 @@ image.
 
 :::
 
+:::warning
+Rolling tags exist only in the `kolla` namespace. In a deployment that uses an OSISM release namespace
+(`docker_namespace: kolla/release/<openstack_version>`), the tag override above resolves to images that do
+not exist and the pull fails with `unknown: artifact ... not found`. Because `keystone_tag` applies to all
+Keystone images, each of them has to be overridden as well, so that they are pulled from the `kolla`
+namespace:
+
+```yaml
+keystone_image: "registry.osism.tech/kolla/keystone"
+keystone_fernet_image: "registry.osism.tech/kolla/keystone-fernet"
+keystone_ssh_image: "registry.osism.tech/kolla/keystone-ssh"
+keystone_httpd_image: "registry.osism.tech/kolla/httpd"
+keystone_tag: "2025.1"  # or "2024.1", "2024.2", "2025.2", depending on your OpenStack release
+```
+
+See [Rolling tags and release tags](../../guides/configuration-guide/openstack/index.md#rolling-tags-and-release-tags).
+:::
+
 ### Mitigation
 
 Because all deployments are affected and the vulnerabilities require only authenticated access,

docs/appendix/security/ossa-2026-022.md

@@ -121,6 +121,20 @@ image. Using rolling tags, configure the following in `environments/kolla/images
 nova_api_tag: "2025.1"  # or "2024.1", "2024.2", "2025.2", depending on your OpenStack release
 ```
 
+:::warning
+Rolling tags exist only in the `kolla` namespace. In a deployment that uses an OSISM release namespace
+(`docker_namespace: kolla/release/<openstack_version>`), the tag override above resolves to an image that
+does not exist and the pull fails with `unknown: artifact ... not found`. The image parameter has to be
+overridden as well, so that this image is pulled from the `kolla` namespace:
+
+```yaml
+nova_api_image: "registry.osism.tech/kolla/nova-api"
+nova_api_tag: "2025.1"  # or "2024.1", "2024.2", "2025.2", depending on your OpenStack release
+```
+
+See [Rolling tags and release tags](../../guides/configuration-guide/openstack/index.md#rolling-tags-and-release-tags).
+:::
+
 ### Mitigation
 
 Because all deployments are affected and exploitation requires only an authenticated user that can

docs/appendix/security/ossa-2026-032.md

@@ -195,7 +195,12 @@ for the Neutron container images via the following change:
 
 This change adds the patch for all four supported releases (2024.1, 2024.2, 2025.1, 2025.2).
 
-A fix will be included in upcoming OSISM releases that ship the patched Neutron container images.
+OSISM 10.2.0 is the first release that ships the patched Neutron container images. It pins the Kolla
+build `0.20260814.0`, in which `neutron-server` of the `kolla/release/2025.1` namespace is tagged
+`26.0.6.20260814` and carries Neutron 26.0.6, the version that contains the fix. Deployments on OSISM
+10.2.0 or later therefore obtain the fix by upgrading and do not need the image overrides described
+below. On OSISM 10.1.0 and earlier, which pin Kolla builds predating this advisory, the release
+namespace does not contain a patched image and the fix can only be obtained through the rolling tags.
 Consult the [OSISM Release Notes](../../release-notes/) for version information and availability.
 
 The vulnerable code path runs in the Neutron API service, so it is sufficient to override the
@@ -206,6 +211,22 @@ The vulnerable code path runs in the Neutron API service, so it is sufficient to
 neutron_server_tag: "2025.1"  # or "2024.1", "2024.2", "2025.2", depending on your OpenStack release
 ```
 
+:::warning
+Rolling tags exist only in the `kolla` namespace. In a deployment that uses an OSISM release namespace
+(`docker_namespace: kolla/release/<openstack_version>`), the tag override above resolves to an image that
+does not exist and the pull fails with `unknown: artifact ... not found`. The image parameter has to be
+overridden as well, so that this image is pulled from the `kolla` namespace:
+
+```yaml
+neutron_server_image: "registry.osism.tech/kolla/neutron-server"
+neutron_server_tag: "2025.1"  # or "2024.1", "2024.2", "2025.2", depending on your OpenStack release
+```
+
+`neutron_rpc_server_image`, `neutron_periodic_worker_image` and `neutron_ovn_maintenance_worker_image`
+default to `neutron_server_image` and are covered by this override. See
+[Rolling tags and release tags](../../guides/configuration-guide/openstack/index.md#rolling-tags-and-release-tags).
+:::
+
 The Neutron agent images (`neutron-openvswitch-agent`, `neutron-l3-agent`, and others) do not contain
 the affected code and do not need to be updated for this issue.
 

docs/guides/configuration-guide/openstack/index.md

@@ -26,6 +26,105 @@ The image tags can be set in the `environments/kolla/images.yml` file.
   barbican_worker_tag: "2023.1"
   ```
 
+### Rolling tags and release tags
+
+Kolla images are published in two namespaces on `registry.osism.tech`, and each namespace uses its own
+tagging scheme. The two schemes are not interchangeable — which tags you can use depends on the
+`docker_namespace` parameter set in `environments/kolla/configuration.yml`.
+
+| Namespace                           | Tag scheme                       | Example           | Meaning                                                               |
+|:------------------------------------|:---------------------------------|:------------------|:----------------------------------------------------------------------|
+| `kolla`                             | OpenStack release                | `2025.1`          | Rolling tag. Always points to the most recent build for that release. |
+| `kolla/release/<openstack_version>` | `<project version>.<build date>` | `26.0.4.20260615` | Immutable tag. Always points to exactly one build.                    |
+
+* **Rolling tags** exist only in the `kolla` namespace. A rolling tag such as `2025.1` is a moving
+  reference: it is republished whenever new images are built for OpenStack 2025.1 (Epoxy), so it always
+  resolves to the latest available build — including the latest security patches. It is a safe choice to
+  keep such a pin in place permanently, but the image it resolves to changes over time.
+
+* **Release tags** exist only in the `kolla/release/<openstack_version>` namespaces, which is what
+  deployments using an OSISM release consume (see
+  [New namespace for Kolla images](../../../release-notes/osism-10.md#new-namespace-for-kolla-images)).
+  These tags are immutable and are pinned per OSISM release, so a deployment always gets the exact same
+  images. The versions are shipped in the `osism/kolla-ansible` image and do not need to be configured.
+
+:::warning
+The `kolla/release/<openstack_version>` namespaces do **not** contain rolling tags. Setting
+`neutron_server_tag: "2025.1"` in a deployment with `docker_namespace: kolla/release/2025.1` therefore
+resolves to `registry.osism.tech/kolla/release/2025.1/neutron-server:2025.1`, which does not exist and
+fails with `unknown: artifact ... not found`.
+:::
+
+To use a rolling tag for a single image in a deployment that otherwise uses release tags, override the
+corresponding `*_image` parameter along with the tag, so that this one image is pulled from the `kolla`
+namespace:
+
+```yaml title="environments/kolla/images.yml"
+neutron_server_image: "registry.osism.tech/kolla/neutron-server"
+neutron_server_tag: "2025.1"
+```
+
+All images of a service that are derived from the same base image are covered by such an override. For
+Neutron, `neutron_rpc_server_image`, `neutron_periodic_worker_image` and
+`neutron_ovn_maintenance_worker_image` default to `neutron_server_image` and therefore do not need to be
+set individually.
+
+### Image parameters and tags of a specific OSISM version
+
+The [002-images-kolla.yml](https://github.com/osism/defaults/blob/main/all/002-images-kolla.yml) file
+linked at the beginning of this section points to the `main` branch of the
+[osism/defaults](https://github.com/osism/defaults) repository, which does not necessarily match the
+OSISM version in use. The parameters of a specific OSISM version are found through the
+[osism/release](https://github.com/osism/release) repository, which pins the version of every OSISM
+component. The `defaults_version` parameter in the `base.yml` of a release pins the tag of the
+`osism/defaults` repository, for OSISM 10.2.0 in
+[10.2.0/base.yml](https://github.com/osism/release/blob/main/10.2.0/base.yml).
+
+```yaml title="10.2.0/base.yml"
+manager_version: 10.2.0
+[...]
+defaults_version: v0.20260712.0
+```
+
+Following that tag, all image parameters available in OSISM 10.2.0 are listed in
+[all/002-images-kolla.yml at v0.20260712.0](https://github.com/osism/defaults/blob/v0.20260712.0/all/002-images-kolla.yml)
+for the OpenStack images and in
+[all/002-images-ceph.yml at v0.20260712.0](https://github.com/osism/defaults/blob/v0.20260712.0/all/002-images-ceph.yml)
+for the Ceph images.
+
+Which tags can be set for such a parameter depends on the tags published in the registry. They can be
+listed per image with `skopeo`, no credentials are required for this. The rolling tags of the Neutron API
+image in the `kolla` namespace:
+
+```console
+$ skopeo list-tags docker://registry.osism.tech/kolla/neutron-server
+{
+    "Repository": "registry.osism.tech/kolla/neutron-server",
+    "Tags": [
+        "2024.1",
+        "2024.2",
+        "2025.1",
+        "2025.2"
+    ]
+}
+```
+
+And the release tags of the same image in the `kolla/release/2025.1` namespace:
+
+```console
+$ skopeo list-tags docker://registry.osism.tech/kolla/release/2025.1/neutron-server
+{
+    "Repository": "registry.osism.tech/kolla/release/2025.1/neutron-server",
+    "Tags": [
+        "26.0.3.20251208",
+        "26.0.3.20260128",
+        "26.0.3.20260328",
+        "26.0.4.20260615",
+        "26.0.6.20260814"
+    ]
+}
+```
+
 ## Endpoints
 
 ### Public endpoints

docs/release-notes/osism-10.md

@@ -215,6 +215,17 @@ different OpenStack versions with a specific OSISM release.
 docker_namespace: kolla/release/2025.1
 ```
 
+The images in this namespace are tagged with an immutable `<project version>.<build date>` tag, for
+example `26.0.4.20260615`. The versions used are pinned per OSISM release and are shipped in the
+`osism/kolla-ansible` image, so they do not need to be configured.
+
+:::warning
+This namespace does not contain the rolling tags named after an OpenStack release, such as `2025.1`.
+Those exist only in the `kolla` namespace. Overriding a single image tag with a rolling tag therefore
+also requires overriding the image itself, see
+[Rolling tags and release tags](../guides/configuration-guide/openstack/index.md#rolling-tags-and-release-tags).
+:::
+
 ### New container registry
 
 Container images are no longer pushed to Quay.io and are only made available on our own