Rolling version skew
During a rolling deployment, silos can advertise different versions of the same grain interface. Orleans separates two questions: compatibility asks whether a requested version can be served by a candidate version, and selection chooses which compatible candidate to use. The grain version manifest, compatibility directors, selectors, and placement service answer those questions together.
Version discovery and selection
Section titled “Version discovery and selection”Each silo contributes supported interface versions to GrainVersionManifest. The cached selector manager keys its result by grain type, interface, and requested version. It obtains available versions, filters them through the configured compatibility director, selects one or more versions, and maps those versions to suitable silos. The cache is invalidated when version or compatibility strategies change.
The built-in strategies have intentionally different upgrade behavior:
| Strategy | Effect |
|---|---|
| Strict compatibility | Only the same interface version is eligible. |
| Backward compatibility | A newer implementation may serve an older request when the director says it is compatible. |
| All versions compatible | Every advertised version is eligible. |
| Latest selector | Choose the highest compatible version. |
| Minimum selector | Choose the lowest compatible version. |
| All compatible selector | Keep all compatible versions as placement candidates. |
The selector converts the compatibility decision into a placement set; applications preserve contract compatibility across that set.
Activation checks
Section titled “Activation checks”Placement chooses a suitable silo, and an activation validates the incoming interface version against its local implementation. An incompatible activation invalidates the stale route and returns the existing message to routing. Version changes can therefore move activation or repeat routing while preserving the logical call.
Wire compatibility is a separate contract
Section titled “Wire compatibility is a separate contract”Version routing requires request and response types readable by both old and new builds for as long as mixed traffic, queued messages, reminders, streams, or persisted state can cross the boundary. Keep serialization IDs stable, add fields with new IDs, retain aliases when CLR names move, and ensure custom codecs skip unknown fields. See serialization and code generation internals for the wire-level rules.
Grain-state compatibility remains an application schema responsibility. Both implementations read the stored representation and tolerate writes from the other while rollback or mixed placement remains possible.
Failure modes and rollout implications
Section titled “Failure modes and rollout implications”- An empty compatible-silo set causes placement to reject or time out the request.
- A stale activation triggers cache invalidation and routing repair for the same logical message; the runtime preserves its message identity while locating a compatible activation.
- Changing a selector or compatibility strategy resets the suitable-silo cache, so subsequent placements reflect the new policy.
- Removing the old implementation before all callers and durable data are compatible can turn a planned rolling deployment into an outage.
The interface versioning guide and deployment and rollback guidance cover configuration and rollout procedures. This runtime decision chain connects interface manifests, compatibility selection, placement, activation validation, and wire compatibility.
Source: GrainVersionManifest, CachedVersionSelectorManager, AllCompatibleVersionsSelector, and ActivationData.