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. For an application SDK, OpenAI-compatible protocol, or runtime behavior change, use the complete development → staging → production protocol rollout. It defines the buffered, streaming, cancellation, error-schema, consumer-canary, fail-closed promotion, and restoration gates; the control-plane binary procedure on this page is a separate compatibility boundary.

​
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.

​
Automate a provider or serving-plan change safely

A provider change is a candidate revision, not an in-place infrastructure edit. Automation should stop before mutation unless the exact combination is present in release evidence:
Follow the exact-combination compatibility check. The dry run must name the provider adapter, runtime and version, compute mode, immutable model, accelerator/topology, region, and replica bounds. Stop safely when any required capability is unsupported, unknown, planned, or lacks the environment-specific qualification required by policy. Do not reinterpret missing evidence as a warning in deployment automation. Only after the dry run and qualification gate pass should automation submit the same reviewed spec:
apply stages an immutable candidate; it does not replace active traffic. Run Release Guard and promote explicitly. If provisioning or validation fails, preserve the operation/evaluation evidence and reject the candidate; the active provider remains routed. The current decision must be ACCEPT for the same active/candidate pair before promotion. After a post-promotion regression, restore the retained previous revision with rollout rollback; never delete the deployment as release recovery.

​
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.

​
Current release support boundary

The current release-candidate line does not yet publish a supported adjacent-release compatibility pair. A mixed-version rolling upgrade is therefore not supported. Use the single-version maintenance procedure below. Do not infer rolling compatibility solely from live protocol numbers.

​
Safe release-candidate upgrade

Because no adjacent pair is currently qualified, a mixed-version rollout is **not a supported release-candidate workflow. Use this maintenance procedure instead:
1

Converge or record active operations

Let ordinary operations finish when possible. For every operation that must cross the maintenance window, retain its ID and current status; do not cancel or recreate it merely to upgrade.
2

Back up and stop the old application replicas

Keep PostgreSQL and provider resources intact. Stop all old InferCrane application replicas so old and new binaries never mutate the database concurrently.
3

Start exactly one new-version replica

Start the candidate image against the preserved database. Its startup migration lock and ledger validation must complete before /readyz becomes healthy. If startup rejects the ledger or a migration fails, stop and follow the release-specific restore procedure; do not edit migration rows.
4

Verify recovery before adding replicas

Confirm the membership list contains only the intended version, incomplete operations resume under fresh leases, and external inventory has not duplicated. Add further same-version replicas only after these checks pass.
This procedure preserves durable operations but includes a control-plane maintenance window. A true rolling upgrade becomes available only when release notes publish an exact old/new pair, overlapping protocol intervals, and compatible schema behavior.

​
Roll back without erasing evidence

If the new binary or migration fails, do not start the old binary against the migrated database and do not delete provider resources. While the failed-version API can still serve read-only requests, export its post-upgrade state as a separate evidence set:
Then stop every InferCrane application replica and preserve the failed database:
If the failed API cannot serve those reads, retain its database snapshot and collect what remains available directly under the incident procedure; never fabricate the missing interval. Provision a separate empty rollback database, point INFERCRANE_DATABASE_URL at it, set INFERCRANE_RESTORE_TARGET_DATABASE to its exact database name, and restore the verified pre-upgrade dump using Backup and restore. The restored database is authoritative only through the backup timestamp. Post-backup exports and the failed-upgrade database remain immutable external audit evidence; the current release cannot reattach those rows automatically to the restored ledger. Before enabling reconciliation, compare the restored active revision and provider identities with the retained exports and read-only provider inventory. Any provider mutation after the backup is a manual reconciliation boundary.

​
Future rolling-upgrade contract

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.