errose28 commented on code in PR #560: URL: https://github.com/apache/ozone-site/pull/560#discussion_r4404125423
########## docs/08-developer-guide/01-develop/05-upgrade-compatibility.md: ########## @@ -150,98 +221,92 @@ Each surface below follows the same shape: **what is considered incompatible** a } ``` -### OM apply transaction / OM RocksDB state +### OM Apply Transaction / OM RocksDB State **Incompatible:** any change to what an OM request writes to RocksDB inside `validateAndUpdateCache`. This includes: - A new column family - A change to the shape of a persisted value class +- Addition or removal of exceptions that abort further processing of the request + - The version without the exception will persist the update to the state machine, while the version with the exception will abort without updating the state machine. - A difference in how a persisted value is calculated, even if the protobuf schema does not change. - For example, an update to quota calculation logic would require version gating. **Pattern:** gate the new persisted behavior in `validateAndUpdateCache` on `ozoneManager.getVersionManager().isAllowed(OzoneManagerVersion.X)` and keep the pre-feature code path for the negative branch. Two OMs can replay the same Ratis transaction while acting as different versions, so the gate keeps their state machines from diverging. -If in doubt, ask: *would an OM acting as apparent v100 and an OM acting as v105, both replaying this transaction from Ratis, arrive at the same DB state?* If not, it needs a gate. +If in doubt, ask: *would an OM acting as apparent version X and an OM acting as apparent version Y, both replaying this transaction from Ratis, arrive at the same DB state?* If not, it needs a gate. -### OM ↔ OM peer RPCs outside Ratis +### OM ↔ OM Peer RPCs Outside Ratis, Including Ratis Snapshot Installation APIs **Incompatible:** adding a required method, or changing the semantics of an existing method, in [`OMAdminProtocol`](https://github.com/apache/ozone/blob/master/hadoop-ozone/common/src/main/java/org/apache/hadoop/ozone/om/protocol/OMAdminProtocol.java) or [`OMInterServiceProtocol`](https://github.com/apache/ozone/blob/master/hadoop-ozone/common/src/main/java/org/apache/hadoop/ozone/om/protocol/OMInterServiceProtocol.java). During a rolling upgrade, peer OMs can be at mixed software versions, so a new method may not exist on the callee. Unlike an unknown protobuf *field*, an unknown *method* fails the RPC outright. -**Pattern:** Callers must not invoke a new inter-OM method until its version is finalized . The method invocation should only proceed if `ozoneManager.getVersionManager().isAllowed(OzoneManagerVersion.X) == true`. Receivers should not implement gating and process the call regardless of their finalization state. Because all components must be upgraded before finalization is invoked, the existence of a finalized OM making the call means that the receiver is in a new enough software version to be able to process the call, even if it is a slow follower which has not yet finalized. +**Pattern:** Callers must not invoke a new inter-OM method until its version is finalized. The method invocation should only proceed if `ozoneManager.getVersionManager().isAllowed(OzoneManagerVersion.X) == true`. Receivers should not implement gating and process the call regardless of their finalization state. Because all components must be upgraded before finalization is invoked, the existence of a finalized OM making the call means that the receiver is in a new enough software version to be able to process the call, even if it is a slow follower which has not yet finalized. This pattern also applies to SCM peer RPCs. -### Ratis state-machine snapshots (OM & SCM) - -**Incompatible:** anything that makes a follower's installed snapshot unreadable by a peer that has not finalized. Snapshot compatibility *is* RocksDB-schema compatibility. - -**Pattern:** if your change adds a new column family, it must not be populated until finalization. Otherwise a follower that installs a snapshot from a new leader ends up holding data an older peer cannot read after a downgrade. Gating the *write* into the new column family on the apparent version is what keeps snapshots portable. Review Comment: This comment is on an older version of the docs. In the current version RocksDB compatibility is covered under `OM Apply Transaction / OM RocksDB State`. Following this automatically handles compatibility of the snapshot contents, so I'll add a new sentence to that section to call that out. The section `OM/SCM ↔ OM/SCM Peer RPCs Outside Ratis, Including Ratis Snapshot Installation APIs` is about API compatibility, not the contents of the snapshot. For example, if a new way to fetch the snapshot from the leader is created, the old one must still be supported until finalization. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
