Skip to main content

ADR-0151: Compatibility matrix held by the signed catalog, not by a compatibility_matrix table

Context​

The reference data model (B13.1) lists a compatibility_matrix table. The Platform Manager decides the compatibility of an installation, an upgrade and a restore from the versions of each service.

Decision​

The compatibility matrix is catalog data, shipped and signed with it (navin-manager/catalog/stack.yaml and each catalog/services/<service>.yaml: version, upgrade.from, upgrade.stateful, upgrade.rollback). The server reads it through services/context.py::supported_versions and services/upgrades.py::compatibility; the restore check (recovery/restore.py::compatibility) compares the versions recorded in the artefact with the target versions. No compatibility_matrix table is created: a copy in the database could drift from the catalog actually deployed, while the catalog is versioned, reviewed and signed with the code that applies it, and travels unchanged in the offline mirror.

Consequences​

Changing the matrix means shipping a catalog; it is audited by the repository history and the signature, not by rows editable at run time. The API exposes the computed result (GET /api/v1/clusters/{cluster_id}/services/{service}/upgrade: allowed, problems with a reason) in English and French.

Evidence​

  • navin-manager/server/tests/test_lifecycle_upgrades.py::test_upgrade_compatibility_refusals: versions outside the matrix are refused.
  • navin-manager/server/tests/test_catalog.py::test_parameters_are_documented_and_valid: catalog schema.