kronos-openstack 0.1.1__tar.gz → 0.2.0__tar.gz

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/.github/workflows/ci.yml

@@ -67,6 +67,26 @@ jobs:
       - run: pip install -e ".[docs]"
       - run: sphinx-build -W -b html docs docs/_build/html
 
+  dco:
+    # Every commit must carry a DCO Signed-off-by line (see CONTRIBUTING.md)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+      - name: Check Signed-off-by on every commit
+        run: |
+          missing=0
+          for sha in $(git rev-list --no-merges \
+              ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}); do
+            if ! git log -1 --format=%B "$sha" | grep -q "^Signed-off-by: "; then
+              echo "::error::commit $sha is missing a Signed-off-by line"
+              missing=1
+            fi
+          done
+          exit "$missing"
+
   genconfig:
     # The generated config reference must be regenerated and committed
     # whenever options change.

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/CLAUDE.md

@@ -217,7 +217,7 @@ at load time because the query has to run against live Prometheus.
 **Adding a new policy field:**
 1. Add to `PolicyConfig` in `models.py` with `Field(...)`
 2. Add cross-field validation via `@model_validator` if needed
-3. Update the sample `policies.yaml` in `internal-documentation/`
+3. Update the sample `etc/kronos/policies.yaml.sample`
 4. Add tests in `tests/unit/policies/test_models.py`
 5. Update this section
 
@@ -454,7 +454,7 @@ of the three may veto a candidate destination.
 
 The cache is invalidated each engine cycle.
 
-Future: NUMA, CPU feature flags, flavor extra specs, soft-rule
+Future: NUMA, flavor extra specs, soft-rule
 penalties in the planner -
 https://docs.openstack.org/nova/latest/user/server-groups.html
 
@@ -798,3 +798,28 @@ Engine notification listener updates cooldown/quarantine state
 4. Hard timeout on migration polling
 5. Post-flight verification (host + status)
 6. Idempotent: pre-flight catches duplicate or stale tasks
+
+
+## CPU compatibility gate
+
+`[engine] require_cpu_compatibility` defaults to false and is independent
+of the Placement claims gate. `PlacementClient.fetch_cpu_traits(hosts)`
+reads `HW_CPU_*` traits using Placement microversion 1.6. The engine
+resolves aggregate/AZ scope before fetching the union once per cycle.
+
+`ConstraintChecker` requires source traits to be a subset of destination
+traits after availability and claims checks, before server-group checks.
+All four movers inherit the check. Pair verdicts and trait data reset
+each cycle. Missing data fails closed. A known empty source set warns
+and passes when the destination also has known data.
+
+Both snapshot entry points capture `placement/cpu_traits.json` when
+enabled. `ReplayPlacementClient` reads it without network access.
+Missing or invalid snapshots fail closed. Claims remain unrecorded,
+so CPU replay requires `enforce_placement_claims = false`.
+
+The host-level rule is approximate. `HW_CPU_*` includes hyperthreading
+as well as mapped instruction flags. Current host configuration can
+differ from a running guest's retained CPU model. Nova remains the
+authoritative migration compatibility check. See the configuration
+reference for behavior and limitations.

kronos_openstack-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to Kronos
+
+Thanks for your interest in Kronos. Contributions of every kind are
+welcome: bug reports, documentation fixes, new constraint checks,
+policy ideas, and operational feedback from real clouds.
+
+## Reporting issues
+
+Open an issue at https://github.com/kronos-openstack/kronos/issues.
+For bugs, include the Kronos version, the OpenStack release, and -
+when planning behaves unexpectedly - a `kronos-record` snapshot if
+you can share one (scrub hostnames if needed). A snapshot lets us
+replay your exact planning cycle offline with `kronos-replay`.
+
+## Development setup
+
+Python 3.12+ is required.
+
+```bash
+git clone https://github.com/kronos-openstack/kronos.git
+cd kronos
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Before you submit
+
+All four gates must pass; CI runs the same commands:
+
+```bash
+pytest tests/
+ruff check kronos/ tests/
+mypy kronos/
+pyright kronos/ tests/
+```
+
+New code needs type hints on public APIs and tests for new behavior.
+Follow the conventions of the module you are editing: the project
+uses oslo.config, oslo.log, and oslo.messaging throughout, and
+ASCII-only punctuation in code, comments, and documentation. If you
+change configuration options, regenerate the config reference:
+
+```bash
+oslo-config-generator --config-file etc/oslo-config-generator/kronos.conf
+```
+
+## Sign your work (DCO)
+
+Every commit must carry a Developer Certificate of Origin sign-off:
+
+```bash
+git commit -s
+```
+
+This appends a `Signed-off-by:` line with your name and email,
+certifying that you have the right to submit the change under the
+project license (see https://developercertificate.org/). CI checks
+every commit in a pull request and fails on missing sign-offs.
+
+## Pull requests
+
+- Keep each PR to one logical change.
+- Describe the operational motivation, not just the code change.
+- The project targets OpenStack ecosystem conventions; expect review
+  feedback aimed at keeping it that way.
+
+## License
+
+By contributing you agree that your contributions are licensed under
+the Apache License 2.0, the same license as the project.

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kronos-openstack
-Version: 0.1.1
+Version: 0.2.0
 Summary: PromQL-driven VM placement engine for OpenStack
 Author-email: Luca Del Monte <luca.delmonte5@gmail.com>, Michele Palazzi <sysdadmin@m1k.cloud>
 License: Apache-2.0
@@ -261,6 +261,11 @@ enforce_placement_claims = true
 # ephemeral root disk is genuinely local.
 enforce_placement_disk = false
 
+# Require destination Placement HW_CPU_* traits to contain all source traits.
+# Missing data blocks moves. Empty source sets warn and pass. Independent of
+# enforce_placement_claims. Nova still checks migrations. (boolean value)
+require_cpu_compatibility = false
+
 [prometheus]
 url = http://prometheus:9090
 
@@ -532,8 +537,7 @@ enforcer, planner) so you can see where cycles are spent.
 
 Planned work:
 
-- **Richer constraints** - NUMA topology, CPU feature flags, and
-  flavor extra specs as additional move filters.
+- **Richer constraints** - NUMA topology, and flavor extra specs as additional move filters.
 
 Suggestions and contributions are welcome - open an issue.
 

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/README.md

@@ -213,6 +213,11 @@ enforce_placement_claims = true
 # ephemeral root disk is genuinely local.
 enforce_placement_disk = false
 
+# Require destination Placement HW_CPU_* traits to contain all source traits.
+# Missing data blocks moves. Empty source sets warn and pass. Independent of
+# enforce_placement_claims. Nova still checks migrations. (boolean value)
+require_cpu_compatibility = false
+
 [prometheus]
 url = http://prometheus:9090
 
@@ -484,8 +489,7 @@ enforcer, planner) so you can see where cycles are spent.
 
 Planned work:
 
-- **Richer constraints** - NUMA topology, CPU feature flags, and
-  flavor extra specs as additional move filters.
+- **Richer constraints** - NUMA topology, and flavor extra specs as additional move filters.
 
 Suggestions and contributions are welcome - open an issue.
 

kronos_openstack-0.2.0/docs/configuration/index.rst

@@ -0,0 +1,98 @@
+Configuration reference
+=======================
+
+Config split
+------------
+
+- ``/etc/kronos/kronos.conf`` - oslo.config INI for daemon settings.
+  Everything the daemons need to run: evaluation interval, dry-run,
+  aggregate scope, availability zone, cooldowns, messaging transport,
+  Prometheus endpoint, Keystone auth.
+- ``/etc/kronos/policies.yaml`` - Pydantic-validated YAML describing
+  the scheduling policies: PromQL queries, thresholds, weights,
+  per-VM profiling queries and fallbacks.
+
+The split is deliberate: policies are a rich, validated document with
+cross-field rules (weights summing to 1.0, one mode per file); daemon
+settings are flat key-value pairs that fit oslo.config.
+
+Full option reference
+---------------------
+
+The complete generated reference - every option of every group,
+including the inherited oslo.log and oslo.messaging options - is
+checked into the repository at ``docs/configuration/kronos.conf.sample``
+and regenerated with:
+
+.. code-block:: console
+
+   oslo-config-generator --config-file etc/oslo-config-generator/kronos.conf
+
+.. literalinclude:: kronos.conf.sample
+   :language: ini
+
+Policies file
+-------------
+
+See ``etc/kronos/policies.yaml.sample`` in the repository for a
+commented example. Load-time invariants:
+
+- policy names are unique;
+- all policies in one file share a ``mode`` (``spread`` or ``pack``);
+- enabled policy ``weight`` values sum to 1.0;
+- ``imbalance_query`` must return per-host values in [0, 1] - enforced
+  at runtime by the scorer, which skips the policy for the cycle (with
+  an error logged) on out-of-range data.
+
+
+CPU compatibility
+-----------------
+
+Set ``[engine] require_cpu_compatibility = true`` to require a
+destination's Placement ``HW_CPU_*`` traits to contain every CPU trait
+reported for the source host. The default is false. This option is
+independent of ``enforce_placement_claims``.
+
+The shared constraint checker applies this rule to spread, pack,
+disabled-host evacuation, and affinity repair. Checks run after host
+availability and capacity claims, before server-group checks. A DEBUG
+message names the rejected host pair and missing traits.
+
+The engine lists Placement providers and reads traits once per in-scope
+host per cycle, deduplicating overlapping aggregates and filtering to
+the configured availability zone. The service user needs
+``placement:resource_providers:list`` and
+``placement:resource_providers:traits:list`` access. The traits endpoint
+uses Placement microversion 1.6. Provider names must match the Nova host
+names used by the engine. Missing source or destination data blocks a
+move. Any traits fetch failure blocks all moves for that cycle.
+
+A successful response containing no ``HW_CPU_*`` traits is different
+from unavailable data. An empty source set permits moves to destinations
+with known data and logs a warning once per cycle that the check is
+blind for that source.
+
+This is a host-level approximation, not a per-instance CPU model check.
+Nova's libvirt driver reports host features for host-model and
+host-passthrough, and a union of configured models for custom mode.
+The prefix also includes ``HW_CPU_HYPERTHREADING``, so the check can
+reject moves for more than instruction-set differences. It can reject
+moves Nova would accept and miss incompatibilities involving unmapped
+flags or guests retaining an older CPU model after reconfiguration.
+Nova's migration pre-check remains authoritative.
+
+Producer source:
+`Nova libvirt CPU trait reporting <https://github.com/openstack/nova/blob/stable/2025.2/nova/virt/libvirt/driver.py>`_.
+API source:
+`Placement provider traits <https://github.com/openstack/placement/blob/stable/2025.2/placement/handlers/trait.py>`_.
+
+When the option is enabled, both ``kronos-record`` and engine SIGUSR1
+snapshots write ``placement/cpu_traits.json``, a mapping from host names
+to sorted trait lists. Failed collection writes an empty mapping.
+Replay reads this file without contacting Placement. Missing files in
+older snapshots fail closed when CPU checking is enabled.
+
+For CPU compatibility replay, enable ``require_cpu_compatibility`` and
+set ``enforce_placement_claims = false``. Capacity claims are not
+recorded by the existing snapshot format. Leaving that gate enabled
+pauses replay planning with an explicit error in the logs.

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/docs/configuration/kronos.conf.sample

@@ -292,6 +292,11 @@
 # aggregate. (boolean value)
 #enforce_placement_disk = false
 
+# Require destination Placement HW_CPU_* traits to contain all source traits.
+# Missing data blocks moves. Empty source sets warn and pass. Independent of
+# enforce_placement_claims. Nova still checks migrations. (boolean value)
+#require_cpu_compatibility = false
+
 
 [executor]
 
@@ -387,6 +392,21 @@
 # Log requests to multiple loggers. (boolean value)
 #split_loggers = false
 
+# An OpenSSL cipher string to set the allowed ciphers for TLS connections. If
+# not specified, the default ciphers from the underlying OpenSSL library are
+# used. (string value)
+#tls_ciphers = <None>
+
+# The minimum TLS version to require for TLS connections. When not specified,
+# the behavior is undefined and defers to the system cryptographic policy.
+# (string value)
+# Possible values:
+# <None> - None - the absence of a setting, defers to the system cryptographic
+# policy
+# 1.2 - TLS 1.2 - enforce minimum TLS version 1.2
+# 1.3 - TLS 1.3 - enforce minimum TLS version 1.3
+#tls_min_version = <None>
+
 # The default service_type for endpoint URL discovery. (string value)
 #service_type = <None>
 
@@ -584,8 +604,7 @@
 # (boolean value)
 # This option is deprecated for removal.
 # Its value may be silently ignored in the future.
-# Reason: Hostname verification should remain enabled once operators have
-# completed the migration.
+# Reason: Verification is always enabled now
 #ssl_enforce_hostname_verification = true
 
 # DEPRECATED: Global toggle for enforcing the OpenSSL FIPS mode. This feature

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/etc/kronos/kronos.conf.sample

@@ -2,6 +2,7 @@
 # debug = false
 
 [engine]
+require_cpu_compatibility = false
 # Seconds between policy evaluation cycles.
 # evaluation_interval = 60
 

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/kronos/clients/placement.py

@@ -206,3 +206,29 @@ class PlacementClient:
             for rc, used in raw.items()
             if rc in TRACKED_RESOURCE_CLASSES
         }
+
+    def fetch_cpu_traits(self, hosts: set[str]) -> dict[str, frozenset[str]]:
+        if not hosts:
+            return {}
+        try:
+            traits: dict[str, frozenset[str]] = {}
+            for rp in self._placement.resource_providers():
+                if rp.name not in hosts:
+                    continue
+                response = self._placement.get(
+                    f"/resource_providers/{rp.id}/traits", microversion="1.6",
+                )
+                response.raise_for_status()
+                raw = response.json()["traits"]
+                if not isinstance(raw, list) or not all(
+                    isinstance(trait, str) for trait in raw
+                ):
+                    raise ValueError(f"Invalid CPU traits response for {rp.name}")
+                traits[rp.name] = frozenset(
+                    trait for trait in raw if trait.startswith("HW_CPU_")
+                )
+            return traits
+        except Exception as exc:
+            raise PlacementClientError(
+                reason=f"Failed to fetch CPU traits: {exc}",
+            ) from exc

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/kronos/cmd/record.py

@@ -15,6 +15,7 @@ from oslo_config import cfg
 from oslo_log import log as logging
 
 from kronos.clients.nova import NovaClient
+from kronos.clients.placement import PlacementClient
 from kronos.clients.prometheus import PrometheusClient
 from kronos.common.config import register_opts
 from kronos.common.snapshot import write_snapshot
@@ -72,8 +73,12 @@ def main() -> int:
 
     nova = NovaClient(CONF)
     prometheus = PrometheusClient(CONF)
+    placement = (
+        PlacementClient(CONF) if CONF.engine.require_cpu_compatibility else None
+    )
     target = write_snapshot(
         parent_dir, nova, prometheus, policies, aggregate_names,
+        placement=placement,
     )
 
     LOG.info("Snapshot written to %s", target)

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/kronos/cmd/replay.py

@@ -22,9 +22,10 @@ from oslo_config import cfg
 from oslo_log import log as logging
 
 from kronos.clients.nova import ComputeService, Instance
+from kronos.clients.placement import PlacementClient, ProviderSnapshot
 from kronos.clients.prometheus import PrometheusHealth, QueryResult
 from kronos.common.config import register_opts
-from kronos.common.exceptions import AggregateNotFound
+from kronos.common.exceptions import AggregateNotFound, PlacementClientError
 from kronos.common.messaging import UNASSIGNED_TOPIC_MARKER
 from kronos.engine.cooldown import CooldownTracker
 from kronos.engine.loop import EngineLoop
@@ -295,6 +296,7 @@ def main() -> int:
         prometheus=prometheus,  # type: ignore[arg-type]
         cooldown=cooldown,
         timings=timings,
+        placement=ReplayPlacementClient(snapshot_dir),
     )
 
     started = time.perf_counter()
@@ -307,3 +309,32 @@ def main() -> int:
         _log_timings(timings, total)
 
     return 0
+
+
+class ReplayPlacementClient(PlacementClient):
+    def __init__(self, snapshot_dir: Path) -> None:
+        self._traits_path = snapshot_dir / "placement" / "cpu_traits.json"
+
+    def fetch_cpu_traits(self, hosts: set[str]) -> dict[str, frozenset[str]]:
+        if not self._traits_path.exists():
+            raise PlacementClientError(reason="Snapshot has no CPU traits")
+        raw = json.loads(self._traits_path.read_text())
+        if not isinstance(raw, dict):
+            raise PlacementClientError(reason="Invalid CPU traits snapshot")
+        traits: dict[str, frozenset[str]] = {}
+        for host, flags in raw.items():
+            if not isinstance(flags, list) or not all(
+                isinstance(flag, str) for flag in flags
+            ):
+                raise PlacementClientError(reason=f"Invalid CPU traits for {host}")
+            if host in hosts:
+                traits[host] = frozenset(
+                    flag for flag in flags if flag.startswith("HW_CPU_")
+                )
+        return traits
+
+    def fetch_snapshots(self) -> dict[str, ProviderSnapshot]:
+        raise PlacementClientError(
+            reason="Placement claims are not recorded. Disable "
+                   "enforce_placement_claims for offline CPU compatibility replay.",
+        )

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/kronos/common/config.py

@@ -250,6 +250,15 @@ engine_opts: list[cfg.Opt] = [
             "identical across all hosts in the aggregate."
         ),
     ),
+    cfg.BoolOpt(
+        "require_cpu_compatibility",
+        default=False,
+        help=(
+            "Require destination Placement HW_CPU_* traits to contain all source "
+            "traits. Missing data blocks moves. Empty source sets warn and pass. "
+            "Independent of enforce_placement_claims. Nova still checks migrations."
+        ),
+    ),
 ]
 
 prometheus_opts: list[cfg.Opt] = [

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/kronos/common/snapshot.py

@@ -27,6 +27,7 @@ from pathlib import Path
 from oslo_log import log as logging
 
 from kronos.clients.nova import NovaClient
+from kronos.clients.placement import PlacementClient
 from kronos.clients.prometheus import PrometheusClient
 from kronos.common.messaging import UNASSIGNED_TOPIC_MARKER
 from kronos.policies.models import PoliciesConfig
@@ -43,6 +44,8 @@ def write_snapshot(
     prometheus: PrometheusClient,
     policies: PoliciesConfig,
     aggregate_names: list[str | None],
+    *,
+    placement: PlacementClient | None = None,
 ) -> Path:
     """Write a complete snapshot under ``parent_dir`` and return its path.
 
@@ -77,7 +80,9 @@ def write_snapshot(
         ),
     )
 
-    _write_nova(nova, aggregate_names, target)
+    hosts = _write_nova(nova, aggregate_names, target)
+    if placement is not None:
+        _write_cpu_traits(placement, hosts, target)
     _write_prometheus(prometheus, policies, target)
 
     (target / "cooldowns.json").write_text(
@@ -98,7 +103,7 @@ def _write_nova(
     nova: NovaClient,
     aggregate_names: list[str | None],
     output_dir: Path,
-) -> None:
+) -> set[str]:
     nova_dir = output_dir / "nova"
     nova_dir.mkdir()
 
@@ -163,6 +168,8 @@ def _write_nova(
         LOG.error("Failed to list compute services", exc_info=True)
         (nova_dir / "services.json").write_text("[]")
 
+    return all_hosts
+
 
 def _write_prometheus(
     prometheus: PrometheusClient,
@@ -234,3 +241,18 @@ def _write_prometheus(
                     policy.name,
                     exc_info=True,
                 )
+
+
+def _write_cpu_traits(
+    placement: PlacementClient, hosts: set[str], output_dir: Path,
+) -> None:
+    directory = output_dir / "placement"
+    directory.mkdir()
+    try:
+        traits = placement.fetch_cpu_traits(hosts)
+    except Exception:
+        LOG.error("Failed to record CPU traits", exc_info=True)
+        traits = {}
+    (directory / "cpu_traits.json").write_text(
+        json.dumps({host: sorted(flags) for host, flags in traits.items()}, indent=2),
+    )

{kronos_openstack-0.1.1 → kronos_openstack-0.2.0}/kronos/engine/constraints.py

@@ -104,13 +104,17 @@ class ConstraintChecker:
 
     Future:
       - NUMA topology
-      - CPU feature flags
       - Flavor extra specs / traits
       - Promote soft rules to planner-side penalties instead of vetoes
     """
 
-    def __init__(self, nova: NovaClient) -> None:
+    def __init__(
+        self, nova: NovaClient, *, require_cpu_compatibility: bool = False,
+    ) -> None:
         self._nova = nova
+        self._require_cpu_compatibility = require_cpu_compatibility
+        self._cpu_traits: dict[str, frozenset[str]] = {}
+        self._cpu_compatibility: dict[tuple[str, str], bool] = {}
         # Lazy-loaded cache; populated on first check() in a cycle.
         self._groups: list[ServerGroup] | None = None
         # Per-cycle nova-compute service map (host -> ComputeService).
@@ -209,6 +213,9 @@ class ConstraintChecker:
         ):
             return False
 
+        if not self._check_cpu_compatibility(vm.host, dest_host):
+            return False
+
         groups = self._get_groups()
         if not groups:
             return True
@@ -382,5 +389,42 @@ class ConstraintChecker:
         """
         self._groups = None
         self._services = None
+        self._cpu_traits = {}
+        self._cpu_compatibility.clear()
         if self._placement_gate is not None:
             self._placement_gate.invalidate()
+
+    def set_cpu_traits(self, traits: dict[str, frozenset[str]]) -> None:
+        self._cpu_traits = dict(traits)
+        self._cpu_compatibility.clear()
+        for host, features in traits.items():
+            if not features:
+                LOG.warning(
+                    "Host %s reports no HW_CPU_* traits. CPU compatibility "
+                    "checking is blind for moves from this host.", host,
+                )
+
+    def _check_cpu_compatibility(self, source: str, destination: str) -> bool:
+        if not self._require_cpu_compatibility:
+            return True
+        pair = (source, destination)
+        if pair in self._cpu_compatibility:
+            return self._cpu_compatibility[pair]
+        source_traits = self._cpu_traits.get(source)
+        destination_traits = self._cpu_traits.get(destination)
+        if source_traits is None or destination_traits is None:
+            compatible = False
+            LOG.debug(
+                "CPU compatibility: %s -> %s rejected (missing host traits).",
+                source, destination,
+            )
+        else:
+            missing = source_traits - destination_traits
+            compatible = not missing
+            if missing:
+                LOG.debug(
+                    "CPU compatibility: %s -> %s rejected (missing traits: %s).",
+                    source, destination, ", ".join(sorted(missing)),
+                )
+        self._cpu_compatibility[pair] = compatible
+        return compatible