fix: max pressure (canonical#743)

* fix : use max-virtual machines for max pressure

* add logline for clamping

* chore: update changelog and pyproject.toml

* add input validation

Author: cbartz

docs/changelog.md

@@ -5,6 +5,7 @@ This changelog documents user-relevant changes to the GitHub runner charm.
 ## 2026-02-27
 
 - Fix a bug where image labels (base,arch) are not propagated to the planner charm.
+- Fix a bug where max_total_virtual_machines is not propagated to the github-runner-manager when used with the planner.
 
 ## 2026-02-25
 

github-runner-manager/pyproject.toml

@@ -3,7 +3,7 @@
 
 [project]
 name = "github-runner-manager"
-version = "0.13.1"
+version = "0.13.2"
 authors = [
     { name = "Canonical IS DevOps", email = "is-devops-team@canonical.com" },
 ]

github-runner-manager/src/github_runner_manager/configuration/base.py

@@ -214,11 +214,36 @@ class NonReactiveCombination(BaseModel):
         image: Information about the image to spawn.
         flavor: Information about the flavor to spawn.
         base_virtual_machines: Number of instances to spawn for this combination.
+        max_total_virtual_machines: Maximum number of instances to spawn. 0 means no cap.
     """
 
     image: "Image"
     flavor: "Flavor"
     base_virtual_machines: int
+    max_total_virtual_machines: int = 0
+
+    @root_validator(pre=False, skip_on_failure=True)
+    @classmethod
+    def check_max_ge_base(cls, values: dict) -> dict:
+        """Validate that max_total_virtual_machines is not below base_virtual_machines.
+
+        Args:
+            values: Values in the pydantic model.
+
+        Raises:
+            ValueError: if max_total_virtual_machines is set but lower than base_virtual_machines.
+
+        Returns:
+            Values in the pydantic model.
+        """
+        max_vms = values.get("max_total_virtual_machines", 0)
+        base_vms = values.get("base_virtual_machines", 0)
+        if 0 < max_vms < base_vms:
+            raise ValueError(
+                f"max_total_virtual_machines ({max_vms}) must be >= base_virtual_machines"
+                f" ({base_vms})"
+            )
+        return values
 
 
 class ReactiveConfiguration(BaseModel):

github-runner-manager/src/github_runner_manager/manager/pressure_reconciler.py

@@ -47,11 +47,13 @@ class PressureReconcilerConfig:
         reconcile_interval: Minutes between timer-based delete reconciliations.
         min_pressure: Minimum desired runner count (floor) for the flavor.
             Also used as fallback when the planner is unavailable.
+        max_pressure: Maximum desired runner count (ceiling). 0 means no cap.
     """
 
     flavor_name: str
     reconcile_interval: int = 5
     min_pressure: int = 0
+    max_pressure: int = 0
 
 
 class PressureReconciler:  # pylint: disable=too-few-public-methods
@@ -228,7 +230,16 @@ def _desired_total_from_pressure(self, pressure: int) -> int:
         Returns:
             The desired total number of runners.
         """
-        return max(pressure, self._config.min_pressure, 0)
+        total = max(pressure, self._config.min_pressure, 0)
+        if self._config.max_pressure > 0 and total > self._config.max_pressure:
+            logger.info(
+                "Pressure %s exceeds max_pressure %s, clamping to %s",
+                pressure,
+                self._config.max_pressure,
+                self._config.max_pressure,
+            )
+            total = self._config.max_pressure
+        return total
 
 
 def build_pressure_reconciler(config: ApplicationConfiguration, lock: Lock) -> PressureReconciler:
@@ -260,6 +271,7 @@ def build_pressure_reconciler(config: ApplicationConfiguration, lock: Lock) -> P
             flavor_name=config.name,
             reconcile_interval=config.reconcile_interval,
             min_pressure=first.base_virtual_machines,
+            max_pressure=first.max_total_virtual_machines,
         ),
         lock=lock,
     )

github-runner-manager/tests/integration/factories.py

@@ -236,6 +236,7 @@ def create_default_config(
                     },
                     "flavor": {"name": openstack_config.flavor or "small", "labels": ["small"]},
                     "base_virtual_machines": 1,
+                    "max_total_virtual_machines": 0,
                 }
             ]
         },

github-runner-manager/tests/unit/manager/test_pressure_reconciler.py

@@ -158,6 +158,35 @@ def _wait(_interval: int) -> bool:
     assert mgr.cleanup_called == 0
 
 
+@pytest.mark.parametrize(
+    "pressure, min_pressure, max_pressure, expected",
+    [
+        pytest.param(5, 0, 10, 5, id="within_bounds"),
+        pytest.param(15, 0, 10, 10, id="clamped_to_max"),
+        pytest.param(1, 3, 10, 3, id="raised_to_min"),
+        pytest.param(15, 3, 10, 10, id="max_wins_over_pressure"),
+        pytest.param(5, 0, 0, 5, id="zero_max_means_no_cap"),
+        pytest.param(-1, 0, 0, 0, id="negative_clamped_to_zero"),
+    ],
+)
+def test_desired_total_from_pressure_respects_bounds(
+    pressure: int, min_pressure: int, max_pressure: int, expected: int
+):
+    """
+    arrange: A reconciler with various min/max pressure configurations.
+    act: Call _desired_total_from_pressure.
+    assert: The result is clamped within the configured bounds.
+    """
+    mgr = _FakeManager()
+    planner = _FakePlanner()
+    cfg = PressureReconcilerConfig(
+        flavor_name="small", min_pressure=min_pressure, max_pressure=max_pressure
+    )
+    reconciler = PressureReconciler(mgr, planner, cfg, lock=Lock())
+
+    assert reconciler._desired_total_from_pressure(pressure) == expected
+
+
 def test_handle_timer_reconcile_uses_desired_total_not_raw_pressure():
     """
     arrange: A reconciler with 4 runners and min_pressure=5.

github-runner-manager/tests/unit/test_config.py

@@ -43,6 +43,7 @@
 non_reactive_configuration:
   combinations:
   - base_virtual_machines: 1
+    max_total_virtual_machines: 2
     flavor:
       labels:
       - flavorlabel
@@ -142,6 +143,7 @@ def app_config_fixture() -> ApplicationConfiguration:
                         labels=["flavorlabel"],
                     ),
                     base_virtual_machines=1,
+                    max_total_virtual_machines=2,
                 )
             ]
         ),
@@ -206,6 +208,38 @@ def test_load_configuration_from_yaml(app_config: ApplicationConfiguration):
     assert loaded_app_config == app_config
 
 
+def test_non_reactive_combination_rejects_max_below_base():
+    """
+    arrange: A NonReactiveCombination where max_total_virtual_machines < base_virtual_machines.
+    act: Construct the model.
+    assert: A ValidationError is raised.
+    """
+    with pytest.raises(
+        ValueError, match="max_total_virtual_machines.*must be.*base_virtual_machines"
+    ):
+        NonReactiveCombination(
+            image=Image(name="img", labels=[]),
+            flavor=Flavor(name="flv", labels=[]),
+            base_virtual_machines=5,
+            max_total_virtual_machines=3,
+        )
+
+
+def test_non_reactive_combination_allows_zero_max():
+    """
+    arrange: A NonReactiveCombination where max_total_virtual_machines is 0 (no cap).
+    act: Construct the model.
+    assert: No error is raised.
+    """
+    combo = NonReactiveCombination(
+        image=Image(name="img", labels=[]),
+        flavor=Flavor(name="flv", labels=[]),
+        base_virtual_machines=5,
+        max_total_virtual_machines=0,
+    )
+    assert combo.max_total_virtual_machines == 0
+
+
 def test_configuration_allows_empty_planner_fields():
     """Planner URL/token are optional for non-planner mode."""
     config = yaml.safe_load(StringIO(SAMPLE_YAML_CONFIGURATION))

src/charm_state.py

@@ -626,6 +626,12 @@ def from_charm(cls, charm: CharmBase) -> "OpenstackRunnerConfig":
                 "Both deprecated and new configuration are set for the number of machines to spawn."
             )
 
+        if 0 < max_total_virtual_machines < base_virtual_machines:
+            raise CharmConfigInvalidError(
+                f"max-total-virtual-machines ({max_total_virtual_machines})"
+                f" must be >= base-virtual-machines ({base_virtual_machines})"
+            )
+
         flavor_label_config = cast(str, charm.config[FLAVOR_LABEL_COMBINATIONS_CONFIG_NAME])
         flavor_label_combinations = _parse_flavor_label_list(flavor_label_config)
         if len(flavor_label_combinations) == 0:

src/factories.py

@@ -129,6 +129,7 @@ def _get_non_reactive_configuration(state: CharmState) -> NonReactiveConfigurati
                 image=image,
                 flavor=flavor,
                 base_virtual_machines=state.runner_config.base_virtual_machines,
+                max_total_virtual_machines=state.runner_config.max_total_virtual_machines,
             )
         ]
     return NonReactiveConfiguration(combinations=combinations)

tests/unit/test_charm_state.py

@@ -846,6 +846,12 @@ def test_parse_virtual_machine_numbers(
             1,
             "deprecated and new configuration are set for the number of machines to spawn",
         ),
+        (
+            0,
+            5,
+            3,
+            "max-total-virtual-machines (3) must be >= base-virtual-machines (5)",
+        ),
     ],
 )
 def test_error_parse_virtual_machine_numbers(