Skip to main content

​
Upgrade and compatibility

InferCrane v1 separates four compatibility surfaces: the control API, DeploymentSpec, integration contracts, and PostgreSQL schema. A passing runtime or provider conformance test does not override the policy for another surface.

​
Before upgrading

  1. Read the release notes and compatibility matrix.
  2. Back up PostgreSQL and verify the dump with pg_restore --list.
  3. Run infercrane plan for representative DeploymentSpecs with the new CLI.
  4. Run local qualification against the exact candidate commit.
  5. Verify provider credentials and inventory with infercrane doctor and infercrane orphans.
  6. Upgrade the control plane before upgrading generated SDKs or automation clients.

​
PostgreSQL migration contract

Migrations are embedded, ordered, forward-only, and transactionally applied under a PostgreSQL advisory lock. The migration ledger stores a SHA-256 checksum for every migration. Startup fails if:
  • a previously applied migration was edited;
  • the ledger has a gap;
  • the database contains a migration unknown to the running binary; or
  • a migration cannot commit atomically.
The first v1 startup backfills checksums for a pre-v1 ledger after matching every known migration name. This is a trust-on-first-v1-upgrade bootstrap: a legacy ledger did not retain enough information to prove the bytes originally executed. Back up and inspect that database before the first v1 startup. Every subsequent startup verifies the persisted checksum. Automated qualification upgrades every historical migration prefix to the current schema. Do not delete ledger rows, edit released SQL files, or start an older binary after a newer migration has run. Restore the pre-upgrade backup if application rollback requires schema rollback.

​
DeploymentSpec

The current file contract is:
Pre-v1 files without these two fields are read as v1 for compatibility. New files should include them. Unknown fields, versions, and kinds fail closed. Additive optional v1 fields are compatible; removing or changing a v1 field requires a future versioned conversion path.

​
Control API and SDKs

/api/v1 is the stable v1 namespace. Within v1:
  • new optional response fields are additive;
  • clients must ignore response fields they do not understand;
  • existing field meaning and error codes do not change silently;
  • removal requires deprecation in release notes for at least two minor releases;
  • generated SDK major versions track the API major version.
CLI human output is not a parsing contract. Automation must use --output json, the generated SDKs, or Terraform.

​
Provider and runtime contracts

Provider Contract infercrane.provider/v1 and Runtime Contract infercrane.runtime/v1 are versioned separately from the product. Registration exposes an adapter to composition; only the capability and qualification inventory establishes evidence for an exact runtime/provider/mode combination.

​
Rolling upgrades

Every live replica registers its binary version and control protocol interval. Startup fails before serving when that interval cannot overlap a live member. Inspect the actual window:
For an adjacent-version rollout, first confirm the release notes declare overlapping protocol intervals. Add one new replica, verify /readyz and the membership list, then remove old replicas one at a time. An expired operation lease is reclaimed by another worker; the old fence token cannot checkpoint or complete work. This is not permission to mix arbitrary schema versions: take a verified backup first and follow the migration compatibility statement for both releases. Rotate server or client certificates by temporarily trusting both CA generations, rolling clients, then servers, and finally removing the old CA. InferCrane reads certificate files at process startup, so each trust change requires a graceful rolling restart.

​
Support window

Release candidates receive best-effort migration fixes and may still change with release notes. For stable releases, security fixes target the latest minor and the immediately preceding minor; provider/runtime compatibility remains scoped to the published matrix and immutable evidence.