Merge pull request #479 from jumpstarter-dev/backport-478-to-release-0.6

Author: mangelajo

docs/source/conf.py

@@ -6,21 +6,18 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import asyncio
 import os
 import sys
 
-import requests
+from jumpstarter_cli_admin.controller import get_latest_compatible_controller_version
 
 sys.path.insert(0, os.path.abspath("../.."))
 
 project = "jumpstarter"
 copyright = "2025, Jumpstarter Contributors"
 author = "Jumpstarter Contributors"
 
-controller_version = requests.get(
-    "https://quay.io/api/v1/repository/jumpstarter-dev/helm/jumpstarter/tag/", params={"limit": 1}
-).json()["tags"][0]["name"]
-
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -54,14 +51,36 @@
 html_favicon = "_static/img/favicon.png"
 html_show_sphinx = False
 
+
+def get_controller_version():
+    name = os.getenv("SPHINX_MULTIVERSION_NAME")
+    if name == "main" or name is None:
+        version = None
+    elif name.startswith("release-"):
+        version = name.removeprefix("release-")
+    else:
+        version = None
+
+    return asyncio.run(get_latest_compatible_controller_version(client_version=version))
+
+
+def get_index_url():
+    name = os.getenv("SPHINX_MULTIVERSION_NAME")
+    if name is None:
+        return "https://pkg.jumpstarter.dev/simple"
+    else:
+        return "https://pkg.jumpstarter.dev/{}/simple".format(name)
+
+
 myst_heading_anchors = 3
 myst_enable_extensions = [
     "substitution",
 ]
 myst_substitutions = {
     "requires_python": ">=3.11",
     "version": "latest",
-    "controller_version": controller_version,
+    "controller_version": get_controller_version(),
+    "index_url": get_index_url(),
 }
 
 doctest_test_doctest_blocks = ""
@@ -91,10 +110,11 @@
 # This replaces the custom bash script approach with built-in functionality
 
 # Tags pattern for html_context["versions"]
-smv_tag_whitelist = r"^v(0\.[5-9](\.\d+)|0\.[1-9][0-9]+(\.\d+)|[1-9]\d*\.\d+\.\d+)$"  # Starting from v0.5.0
-smv_branch_whitelist = r"^(main|master)$"  # Only include main/master branch
-smv_remote_whitelist = None
-smv_released_pattern = r"^v[0-9]+\.[0-9]+\.[0-9]+$"  # Tags that are considered releases
+smv_tag_whitelist = r"$^" # Ignore all tags
+smv_branch_whitelist = r"^(main|release-\d+\.\d+)$" # Include all release branches and main
+smv_remote_whitelist = r'^(origin|upstream)$' # Include branches from origin and upstream
+smv_prefer_remote_refs = True
+# smv_released_pattern = r"^v[0-9]+\.[0-9]+\.[0-9]+$"  # Tags that are considered releases
 smv_outputdir_format = "{ref.name}"  # Directory name format
 
 # Ensure static files are copied to all versions

docs/source/getting-started/installation/packages.md

@@ -20,19 +20,21 @@ tools you need to run an exporter or interact with your hardware as a client.
 Install the Python package using `pip` or a similar tool. You need Python
 {{requires_python}}:
 
-```shell
-$ pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple/ jumpstarter-all
+```{code-block} shell
+:substitutions:
+$ pip3 install --extra-index-url {{index_url}} jumpstarter-all
 $ mkdir -p "${HOME}/.config/jumpstarter/"
 $ sudo mkdir /etc/jumpstarter
 ```
 
 The command above installs packages globally. For library usage, we recommend
 installing in a virtual environment instead:
 
-```shell
+```{code-block} shell
+:substitutions:
 $ python3 -m venv ~/.venv/jumpstarter
 $ source ~/.venv/jumpstarter/bin/activate
-$ pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple/ jumpstarter-all
+$ pip3 install --extra-index-url {{index_url}} jumpstarter-all
 ```
 
 Additional package indexes are available, this is a complete list of our indexes:

packages/jumpstarter-cli-admin/jumpstarter_cli_admin/controller.py

@@ -0,0 +1,54 @@
+import aiohttp
+import semver
+from jumpstarter_cli_common.version import get_client_version
+from packaging.version import Version
+
+
+async def get_latest_compatible_controller_version(
+    client_version: str | None = None,
+):
+    if client_version is None:
+        client_version = Version(get_client_version())
+    else:
+        client_version = Version(client_version)
+
+    async with aiohttp.ClientSession(
+        raise_for_status=True,
+    ) as session:
+        try:
+            async with session.get(
+                "https://quay.io/api/v1/repository/jumpstarter-dev/helm/jumpstarter/tag/",
+                timeout=aiohttp.ClientTimeout(total=30),
+            ) as resp:
+                resp = await resp.json()
+        except Exception as e:
+            raise RuntimeError(f"Failed to fetch controller versions: {e}") from e
+
+    compatible = set()
+    fallback = set()
+
+    if not isinstance(resp, dict) or "tags" not in resp or not isinstance(resp["tags"], list):
+        raise RuntimeError("Unexpected response fetching controller version")
+
+    for tag in resp["tags"]:
+        if not isinstance(tag, dict) or "name" not in tag:
+            continue  # Skip malformed tag entries
+
+        try:
+            version = semver.VersionInfo.parse(tag["name"])
+        except ValueError:
+            continue  # ignore invalid versions
+
+        if version.major == client_version.major and version.minor == client_version.minor:
+            compatible.add(version)
+        else:
+            fallback.add(version)
+
+    if compatible:
+        selected = max(compatible)
+    elif fallback:
+        selected = max(fallback)
+    else:
+        raise ValueError("No valid controller versions found in the repository")
+
+    return str(selected)

packages/jumpstarter-cli-admin/jumpstarter_cli_admin/install.py

@@ -2,18 +2,12 @@
 
 import asyncclick as click
 from jumpstarter_cli_common.opt import opt_context, opt_kubeconfig
-from jumpstarter_cli_common.version import get_client_version
 from jumpstarter_kubernetes import helm_installed, install_helm_chart
 
+from .controller import get_latest_compatible_controller_version
 from jumpstarter.common.ipaddr import get_ip_address
 
 
-def get_chart_version() -> str:
-    client_version = get_client_version()
-    parts = client_version.split(".")
-    return f"{parts[0].replace('v', '')}.{parts[1]}.{parts[2]}"
-
-
 @click.command
 @click.option("--helm", type=str, help="Path or name of a helm executable", default="helm")
 @click.option("--name", type=str, help="The name of the chart installation", default="jumpstarter")
@@ -34,7 +28,7 @@ def get_chart_version() -> str:
 @click.option("--nodeport", "mode", flag_value="nodeport", help="Use Nodeport routing (recommended)", default=True)
 @click.option("--ingress", "mode", flag_value="ingress", help="Use a Kubernetes ingress")
 @click.option("--route", "mode", flag_value="route", help="Use an OpenShift route")
-@click.option("-v", "--version", help="The version of the service to install", default=get_chart_version())
+@click.option("-v", "--version", help="The version of the service to install", default=None)
 @opt_kubeconfig
 @opt_context
 async def install(
@@ -69,6 +63,9 @@ async def install(
     if router_endpoint is None:
         router_endpoint = f"router.{basedomain}:8083"
 
+    if version is None:
+        version = await get_latest_compatible_controller_version()
+
     click.echo(f'Installing Jumpstarter service v{version} in namespace "{namespace}" with Helm\n')
     click.echo(f"Chart URI: {chart}")
     click.echo(f"Chart Version: {version}")

packages/jumpstarter-cli-admin/pyproject.toml

@@ -6,7 +6,13 @@ authors = [{ name = "Kirk Brauer", email = "kbrauer@hatci.com" }]
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.11"
-dependencies = ["jumpstarter-cli-common", "jumpstarter-kubernetes"]
+dependencies = [
+    "aiohttp>=3.11.18",
+    "jumpstarter-cli-common",
+    "jumpstarter-kubernetes",
+    "packaging>=25.0",
+    "semver~=2.13",
+]
 
 [dependency-groups]
 dev = [