Explicitly Version Services

[nuthanmunaiah]

Description

As of this moment, no service is explicitly versioned other than the version assigned to the corresponding container image that the service is packaged in. As as result, expressing dependency between difference versions of services is not possible. For instance, a recent change to the project service introduced a new field to the response from the project.get service method. As a result of this change, services that depend on the project service (repository service for instance) had to be updated to propagate the change in response from project.get. While breaking changes like these are unavoidable, the dependent service (repository, in this case) must continue to be operational using an earlier version of the project service. However, the simultaneous running of two versions of a service is not possible in the current implementation because both versions of the service will be named the same (in the name attribute of the associated Nameko service class).

Proposal

A proposed solution, one that was suggested by the creator of Nameko, is to include a version in the service name.

The proposed solution may be better understood using the example from earlier. Consider two services, repository and project, with repository service being dependent on the project service. The proposed solution is described using the following hypothetical scenarios:

• Assume that version 0.1.0-alpha of the repository service depends on version 0.1.0-alpha of the project service. The service name of version 0.1.0-alpha of the project service will be project@0.x.x-alpha.¹ The repository service will no longer use RpcProxy('project') to define its dependency on the project service but RpcProxy('project@0.x.x-alpha').
• Assume that the project service requires a breaking change (like in Issue Add id to Project in project Service #31), the new version of the service will have its name be project@1.x.x-alpha. Since the new version of the service will be packaged in its own versioned container image, it can be run in parallel with its earlier version. When the repository service is ready to migrate its dependency on the project service to the latest version, RpcProxy('project@0.x.x-alpha') is changed to RpcProxy('project@1.x.x-alpha') and the breaking changes the handled appropriately.

¹ Version follows the Semantic Versioning convention but MINOR and PATCH components are ignored because the MAJOR component is sufficient to communicate incompatible changes.

Resources

• APIs as infrastructure: future-proofing Stripe with versioning by Stripe Engineering.
• Versioning by Google Cloud.

[nuthanmunaiah]

The proposed solution has a limitation: if the breaking change to a service involves a change to the schema of the database owned by the service, having two version of the service will require two versions of the database schema to exist as well. While having two versions of the database schema is an acceptable mitigation of the limitation, it is likely that the data in the database will diverge. There are two possible solutions to the consequence of having two versions of the database schema.

• Allow the data to diverge with the intention to migrate the data from the older version of the database to the newer version when the older version of the service is being sunset.
• Avoid having two versions of the database schema by having an adapter implementing the contract of the older version of the service adapting method invocations to the newer version of the service.