Product Versioning Microservices

Micro Service Versioning

First of all ensure Semantic Versioning (SemVer) is strictly followed by the micro services. Not doing this will sooner or later lead to incompatibility problems.

Capture only API changes in that version, don't mix it up with micro service internal versioning (e.g. DB schema versioning for a service that has a DB).

Product Versioning

Introduce a version for the product as you already suggested. Following SemVer makes sense here, too, but may need to be loosened to meet marketing needs (e.g. allow to make a major version increment even though SemVer would require only a minor version increment). In extreme cases, use dedicated "technical versions" and "marketing versions". This is however more complicated for the customers, too.

Also note that you will need to define what the SemVer version means in terms of your application, since the application as a whole has no "API".

Dependency Management

Now a specific product version is a list of micro services of specific versions. Note that this is essentially dependency management in the same sense as apt, npm, bower, etc implement. How sophisticated your solution needs to be is difficult to say, but I recommend to at least support the notion of "minimum required versions". If docker has a built-in mechanism, try to use that one (I don't know docker very well, so I can't tell).

With this, you are e.g. able to specify that your product at version 4.8.12 requires service A at version 1.12.0 and service B at 3.0.4.

The update mechanism should then follow a strategy that adheres to SemVer. This means that installing a specific product version automatically installs the newest services with the same major version. In the example above, this could e.g. install 1.12.2 of service A and 3.3.0 of service B. Providing a mechanism to keep already installed services that meet the dependency requirement may be a good idea, so that users don't get annoyed by the update mechanism.

Literature uses a 5 dimensional model for this:

• version (wanting to change)
• status (life cycle: create, test, deploy, retire)
• view (source, deployment, documentation)
• hierarchy (product, microservice)
• variant (largely similar, describing the differences, product families)

Most systems only handle a few of these dimensions. To handle all five, you have to describe (fix) your development process.

When only looking at version plus hierarchy, as you do here with product and microservice versioned separately: product version should change as soon as users of the product can notice something different. You might want to signal that from the microservice versioning by using major-minor numbering: minor should not affect the product version, major should.Or you could use version ranges/semantic versioning.

The reference:

Managing design data: the five dimensions of CAD frameworks, configuration management, and product data management.van den Hamer, P. Lepoeter, K.Philips Res., Eindhoven;

This paper appears in: Proceedings of the IEEEPublication Date: Jan 1996Volume: 84, Issue: 1On page(s): 42-56ISSN: 0018-9219References Cited: 26CODEN: IEEPADINSPEC Accession Number: 5175049Digital Object Identifier: 10.1109/5.476025Current Version Published: 2002-08-06