Major A/B Upgrade

uprade.md

Backwards incompatible change to the persistence

Backwards incompatible changes to persistence always require at least two upgrade steps to encapsulate migration without causing downtime.

The REST service has a new required field

1. Create a new REST service artifact "B" which creates the field and treats it as optional in read operations but required in write operations with an incremented minor version.
2. Create a migration artifact (or include migration in the artifact from step 1) which populates the field. A/B deploy "B".
3. Create a new REST service artifact "C" which treats the field as required with an incremented minor version.
4. Wait until the migration is complete, then A/B deploy C.

The REST service dramatically changes its underlying persistence (for example from an SQL DB to a NoSQL DB)

1. Create a new REST service artifact "B" which writes to both the old and the new persistence. Give it an incremented minor version.
2. Create a migration artifact (or include migration in the artifact from step 1) A/B deploy "B".
3. Create a new REST service artifact which updates only the new persistence format, and give it an incremented minor version.
4. Wait until the migration is complete, then A/B deploy C.

Dependent REST services

REST services Purple and Green consume functionality offered by the REST service Blue. REST services Purple and Orange consume REST service Red. REST service Brown consumes Purple, Orange, and Green.

Backwards compatible changes to primary service API

A new feature requires changes in Purple, and those changes in Purple place new requirements on Blue that can be solved with backwards compatible changes.

1. Create a new version of Blue's artifact which contains the changes.
2. Create a new version of Purple’s artifact which contains the changes dependent on Red’s changes.
3. A/B deploy the new version of Blue.
4. A/B deploy the new version of Purple.

Because the changes are backwards compatible, a new version of the remaining services is not necessary.

Backwards incompatible changes to API

A new feature requires changes in Purple, and those changes in Purple place new requirements on Blue that can only be solved with backwards incompatible changes.

1. Create a new minor version of Blue's artifact which contains both the old and the new API.
2. Create a new version of Purple’s artifact which contains the changes dependent on Blue’s changes.
3. A/B deploy the new version of Blue.
4. A/B deploy the new version of Purple.
5. (optionally) Create a new major version of Blue’s artifact which removes the old API, and A/B deploy that.

Changes to persistence

As long as there is no API change involved, upgrades of REST services with changed persistence can be handled exactly as though the REST service were isolated. It doesn’t matter whether they are backwards compatible or incompatible. For migrations though the sequence of versions may matter.