Deploy new grain interface versions

A safe rolling upgrade combines version routing with an application contract that newer implementations can honor for older callers.

Prepare the contract

Before deployment:

1. Keep existing method identities, parameter meanings, return meanings, and serialized payloads compatible.
2. Add new behavior using new methods or optional/version-tolerant payload fields.
3. Make the new implementation able to process every request sent by still-deployed callers.
4. Make persisted state readable by both versions if rollback is required.
5. Test mixed caller and silo versions, not only each version in isolation.

Apply a higher [Version] value only after defining this contract. The number asserts routing compatibility; it doesn’t create compatibility.

Rolling upgrade

The default combination works for a backward-compatible rollout:

siloBuilder.Configure<GrainVersioningOptions>(options =>
{
    options.DefaultCompatibilityStrategy = nameof(BackwardCompatible);
    options.DefaultVersionSelectorStrategy = nameof(AllCompatibleVersions);
});

Then:

1. Start version 2 silos while version 1 silos and callers remain.
2. Version 1 requests can use version 1 or version 2 activations.
3. Start version 2 callers only after enough version 2 silos are ready.
4. A version 2 request can’t use a version 1 activation. If it reaches one, Orleans deactivates that activation and places a compatible version.
5. Drain version 1 callers, then version 1 silos.
6. Keep the backward-compatible contract until rollback is no longer required.

Use LatestVersion when new activations should prefer the newest compatible implementation. Use MinimumVersion when new activations should stay on the lowest compatible version during staged validation. Neither strategy upgrades compatible activations proactively.

Rollback

Routing rollback is only safe if the older code can read state and messages written by the newer code. If version 2 writes an incompatible storage representation or emits incompatible payloads, stopping version 2 silos doesn’t restore compatibility.

Plan data evolution and interface evolution together:

• Deploy backward-compatible readers first.
• Delay irreversible writes until rollback is no longer needed.
• Use operation and schema version fields where semantics can diverge.
• Exercise rollback in a mixed-version test cluster.

Observe the rollout

Monitor incompatible-request deactivations, activation placement by version, failed placements, serialization failures, and state-read failures. A rising rate of replacement activations can indicate incompatible callers sharing hot grain identities or an overly strict strategy.