apply: resolve the release up front

Collection expansion can now filter on the release, but nothing supplies
one. Resolve it in take_action and pass it down, with --openstack-version
overriding the versions file.

The resolution happens before the dispatch loop, not inside it. That
loop iterates the //-separated entries and each handle_collection call
ends in apply_async(), so resolving per entry would let
"osism apply collection-monitoring//nutshell" schedule monitoring and
only then fail on nutshell, having already touched the cluster. Done up
front, a failed resolution schedules nothing at all, and the release is
resolved exactly once, so every entry and every level of the recursion
sees the same value even if the versions file changes mid-run.

The lookup is skipped entirely for collections that contain no bounded
roles, which is eight of the eleven, so such a command cannot fail on
any of this. When it is needed and fails, the three causes are reported
differently -- an unparseable value is already a sentence and is printed
as is, while a missing file or key is appended to one naming the
affected collections -- followed by the roles that needed the release
and how to supply it. The advice names no file to edit: the versions
file belongs to the kolla-ansible container, so the two ways an operator
can supply a release are the environment variable and the flag.

--openstack-version deliberately does not default from the environment
the way sync.py does: openstack_release already consults it, and reading
it here would make the override always truthy. Nor does it default to a
release, which would be the silent guess this all exists to avoid. Note
that argparse.REMAINDER on the trailing arguments swallows any flag
placed after the collection name, so both the help text and the error
advice lead with the environment variable, which is order-independent.

Bounds stay out of the single-role path: "osism apply <role>" never
consults them, because a bound is collection membership and not a claim
that the play exists.

Assisted-by: Claude:claude-opus-5
Signed-off-by: Roger Luethi <luethi@osism.tech>

Author: ideaship

osism/commands/apply.py

@@ -107,6 +107,19 @@ def get_parser(self, prog_name):
             help="Dry run, do not initiate tasks (for collections only)",
             action="store_true",
         )
+        parser.add_argument(
+            "--openstack-version",
+            default=None,
+            type=str,
+            help=(
+                "OpenStack release the collection is applied to, e.g. 2026.1. "
+                "Collections deploy a few roles only on certain releases (redis "
+                "up to 2025.1, valkey from 2025.2). Read from openstack_version "
+                "in /interface/versions/kolla-ansible.yml when not given. Must "
+                "be given before the collection name, or it is swallowed as an "
+                "Ansible argument. (env: OPENSTACK_VERSION)"
+            ),
+        )
         parser.add_argument(
             "--show-tree",
             dest="show_tree",
@@ -329,6 +342,49 @@ def handle_collection(
 
         return 0
 
+    def _resolve_release(self, override, bounded):
+        """Return the deployed release, or exit reporting why it is unknown.
+
+        ``bounded`` maps collection name to the release-bounded roles it
+        contains; it is used only to name what needed the release.
+        """
+        from osism.data.releases import (
+            ReleaseUndetermined,
+            ReleaseUnparseable,
+            openstack_release,
+        )
+
+        try:
+            return openstack_release(override)
+        except ReleaseUnparseable as exc:
+            # Already a complete sentence.
+            logger.error(str(exc))
+        except ReleaseUndetermined as exc:
+            names = ", ".join(sorted(bounded))
+            noun = "Collection" if len(bounded) == 1 else "Collections"
+            verb = "contains" if len(bounded) == 1 else "contain"
+            logger.error(
+                f"{noun} {names} {verb} roles that depend on the OpenStack "
+                f"release, but the release could not be determined: {exc}"
+            )
+
+        # One role can appear in several collections; report it once.
+        descriptions = {}
+        for roles in bounded.values():
+            for role in roles:
+                descriptions[role.name] = role.bound_description()
+
+        affected = ", ".join(
+            f"{name} ({descriptions[name]})" for name in sorted(descriptions)
+        )
+        logger.error(f"Affected roles: {affected}")
+        logger.error(
+            "Supply the release with OPENSTACK_VERSION=<release> osism apply "
+            "<collection>, or with --openstack-version <release> before the "
+            "collection name."
+        )
+        exit(1)
+
     def _prepare_task(
         self,
         arguments,
@@ -502,6 +558,21 @@ def take_action(self, parsed_args):
 
         rc = 0
 
+        # Resolve the release before the dispatch loop below, not inside it: each
+        # iteration ends in apply_async(), so resolving per entry would let an
+        # earlier collection reach the cluster before a later one failed.
+        release = None
+        if role:
+            bounded = {}
+            for entry in role.split("//"):
+                if entry in enums.MAP_ROLE2ROLE:
+                    found = list(enums.bounded_roles(enums.MAP_ROLE2ROLE[entry]))
+                    if found:
+                        bounded[entry] = found
+
+            if bounded:
+                release = self._resolve_release(parsed_args.openstack_version, bounded)
+
         if not role:
             table = []
             for role in MAP_ROLE2ENVIRONMENT:
@@ -529,6 +600,7 @@ def take_action(self, parsed_args):
                         retry,
                         dry_run,
                         show_tree,
+                        release=release,
                     )
                     if rc != 0:
                         outer_break = True