Interface versions and compatibility¶
Checking interface compatibility before deployment¶
Validation fails when a document's schema name or version differs from the pair its Narwhal reader supports.
Print the installed contract manifest:
The contracts object of the narwhal.contract-manifest document maps each manifest key to these fields:
| Field | Meaning |
|---|---|
schema |
Interface schema name. |
write |
Version the release writes. |
read |
Versions the release accepts. |
Interface versions in this release:
| Interface | Schema | Version | Manifest key |
|---|---|---|---|
| Narwhal fleet configuration | narwhal.fleet |
2 | fleet |
| Effective fleet configuration | narwhal.effective-config |
2 | effective_config |
| Engine profile store | narwhal.profiles |
1 | profiles |
| Engine attestation | narwhal.attestation |
1 | attestation |
| Router state handoff | narwhal.handoff |
1 | handoff |
| Router lease | narwhal.router-lease |
1 | lease |
| Engine lifecycle | narwhal.lifecycle |
1 | lifecycle |
| Request journal | narwhal.journal |
1 | journal |
| Live state | narwhal.state |
1 | state |
| Prometheus metrics | narwhal.metrics |
2 | metrics |
| Command result | narwhal.command-result |
1 | command_result |
| Contract manifest | narwhal.contract-manifest |
1 | cli |
| Diagnostic bundle | narwhal.diagnostic-bundle |
1 | diagnostic_bundle |
To compare manifests:
-
Save the manifest from each environment:
-
Compare the two files:
-
Keep the previous release's code, configuration, profiles, and state together as a rollback set.
When the manifests are identical, installed-release documents pass validation on the candidate. When schema or write changes for an interface, that interface's installed-release documents fail validation on the candidate.
Schema version changes¶
The schema version of each interface, including the command result envelope, changes when a field is renamed, removed, or retyped. A metrics version also changes when an existing series gains a label.
Metrics version 2 adds the reason label to narwhal_failed_total, narwhal_rejected_total, and narwhal_expired_total, the cause label to narwhal_refused_total, and the stage label to narwhal_queue_wait_seconds. It also adds the narwhal_admission_inflight, narwhal_admission_inflight_limit, narwhal_router_loop_lag_seconds, narwhal_request_sizing_delay_seconds, and narwhal_saturation_threshold_seconds gauges.
Fleet configuration version 2 and effective fleet configuration version 2 remove serving.prefill_concurrency, serving.decode_concurrency and serving.handoff_timeout_s. The router sets engine seats and each producer's KV handoff bound from engine attestation in their place. Delete the three keys and set schema_version to 2 to upgrade a version 1 fleet file.