Microservice Version Management

A New Kind of Versioning in Cloud-Native Architecture

A New Kind of Versioning

Microservice version management is becoming increasingly important as we move into cloud-native development, managing thousands of objects that make up the software supply chain. Ask yourself, “what does the future look like when I’m managing and tracking hundreds of microservices that make up a single version of my software solution?” You will need more than an Excel spreadsheet to track and version microservices. Microservices are game-changers in terms of how we develop and deliver software.

In the past, we have relied on a monolithic ‘build’ approach where all source code and libraries are compiled and linked, and released simultaneously to end users. The build process ‘statically linked’ the binaries and created a release candidate ‘version.’ The monolithic build performed the job of tracking the changes that went into the binaries we sent to production.  Tracking the versions of the libraries was done by the build with the help of a version repository such as Git.

With microservices, we have independently deployed functions with no static linking. Linking is done at runtime via APIs. While solving many problems, this approach makes it difficult to track the versions of services our application is using.  One of the most common questions is, “How do I know what version of a service is running in any single cluster?” Drift is a common issue in a microservices architecture. A method for solving this problem is to track microservice versions as they move across the pipeline and are installed into different clusters. This article reviews how to version microservices, strategies and best practices, and critical features for versioning container content.

What is a Microservice?

Before we get to microservice version management, let’s start from the top. What is a microservice, and how do we decompose a monolithic application into Services?

Defining a Service

Here’s how Chris Richardson of CloudFoundry fame defines a Service:

  • A service should implement a small set of strongly related functions
  • Services that change together should be packaged together
  • The Service can be changed without affecting clients
  • And each team that owns one or more services must be autonomous. A team must be able to develop and deploy services with minimal collaboration with other teams.   

With microservices, we let go of the concept of monolithic software applications and linear pipelines. We instead have a non-linear configuration of different microservices that represents the ‘logical’ microservice application.

For managing these microservice applications, we need to understand what is in this ‘microservices soup’ in terms of ownership, usage, and microservice configurations. We need to see the whole picture or what we can call the ‘monolithic equivalent.’ This is the reason microservices versioning is important.

What is Versioning in Microservices?

In microservices, ‘versioning’ means tracking not just the changes in your container but all of the attributes of the service, including key-value pairs, SBOMs, CVEs, licenses, swagger details, consuming applications, and deployment metadata. The ability to track and manage versions of microservices is critical and the only way to see the changes between two versions of the same microservice. 

Microservices Versioning Addresses Microservice Drift

As you begin implementing microservice applications, you will quickly learn about microservice ‘drift.’ Drift is created when you have different versions of a single microservice running in multiple clusters and Namespaces. In the below example, all three websites, the candy store, clothing store, and toy store, use a set of common microservices including the Shipping service. Notice that ‘drift’ has occurred at the clothing store, which continues to be one version behind.

microservice versioning for drift


Most DevOps engineers will tell you when they have a new version of a microservice to release, and they will deploy it to all locations simultaneously to avoid drift.

This is not ideal as it stands in the way of Blue/Green, canary or rolling deployments where updates are pushed out in a more methodical way to avoid potential errors. What is needed is a way to track the microservice version along with where it is running to support these deployment models.

In addition, in some organizations, not all teams may want to take a new version of a common microservice – at least not a first. There may be a good reason the clothing store website SRE chooses to stay a version back.

Finally, we need to think about supporting Development, Test, and Production stages and understand which versions of the microservice are running in each. To do this, we use microservice versioning, which allows us the flexibility to support different versions running in different clusters.

Versioning microservices goes well beyond registering them to an image repository. The more data you can include in your versioning strategy, the better.

Best Practices for Microservices Versioning

How do we version microservices to improve their use and success in building microservice applications? Important to remember in versioning microservices is that they are deployed independently and frequently. Second, a microservice is more than just a container image. It has many attributes that need to be versioned and tracked. The following best practices should be considered when defining a microservices versioning strategy:

  • Best Practice #1: The attributes of your microservice go beyond the contents of your container. Versioning the SBOM, CVE, licensing, Swagger details, Key-Value pairs, deployment logic, and endpoint configurations are all part of your microservice’s configuration and should also be versioned and tracked.
  • Best Practice #2: Don’t change the name of your microservice, only update the image value with the image tag in your Kubernetes deployment file.
  • Best Practice #3: Logically track a version number for every release. Use semantic versioning. Calendar versioning can get confusing if a service is changed multiple times in a single day.
  • Best Practice #4: Use the Git Commit SHA in the semantic versioning number. This helps connect back to the developer’s change.
  • Best Practice #5: Logically track the microservice’s consuming applications as part of your versioning strategy. Using this best practice will give you a clear picture of their impact.
  • Best Practice #6: Include a snapshot of your service-to-service API endpoint relationships.

Versioning microservices goes well beyond registering them to an image repository. The more data you can include in your versioning strategy the better.

microservice versioning
Get the Whitepaper

Microservices at scale offer new challenges in managing your software supply chain. Learn how DeployHub is solving this with microservice versioning.

Microservice Version Management with DeployHub

DeployHub is used to simplify the complexities of cloud-native development, with built-in microservice versioning designed to create a unified view of all your services. Here are some features of using DeployHub for microservice versioning.

  • Unified microservice catalog
  • Features for Versioning Container Content
  • Microservice Organization

A Unified Microservice Catalog

A hosted unified microservice catalog tool simplifies the use of microservices by versioning and tracking them, creating a clear picture of the supply chain across all clusters. It was developed to be a central dashboard to show usage, dependencies, deployment configurations, and inventory.

DeployHub’s version management shows what microservice is in a container, who is using it, where it is running, and the microservices relationship to other services. Most interesting is DeployHub’s ability to track a microservice version’s ‘blast radius’ even before you deploy. The blast radius shows who will be impacted if a new version is released.

DeployHub also versions database updates, environment variables, Kubernetes configurations, infrastructure components, SBOMS, CVEs, application artifacts, and other critical parts of your software release.

Critical Features for Versioning Container Content

When we created DeployHub, we saw the following versioning features critical to cloud-native development:

  • Support Domain-Driven Design (DDD) with sub-domains to easily organize microservices.
  • Track microservice ownership and details.
  • Encourage re-use and collaboration of microservices.
  • Support external deployment engines for inventory tracking.
  • Track a microservice version to a microservice application providing a logical view of all microservice applications.

DeployHub uses the concepts of domains, environment, application, and component to provide the framework for managing services in their containers. Some of these terms we have seen before, like environment and application. However, terms like domains and components are new concepts that relate to how your microservices are organized.

To ensure we are all on the same page, the term environment is a collection of endpoints where your application will be deployed. Most traditional Application Release Automation solutions use these terms and concepts for software deployments.

Microservice Organization

To support the organization of microservices, DeployHub follows a Domain-Driven Design (DDD)to categorize microservices and components.

  • DeployHub defines an application as a collection of components. Your microservices map directly to components. Your application could have any combination of component types, such as a front-end microservice, and a collection of common microservices.
  • A Domain is both an object unique to DeployHub and a concept used to organize microservices based on lines of business or ‘problems’. A domain is often referred to as Domain Driven Design (DDD) and is a critical feature of microservice versioning and versioning container content.

DeployHub Team (based on Ortelius open source) is a microservice dashboard that provides you with two levels of Domains – a Global Domain and a Project Domain. DeployHub Pro supports a third level called the ‘Divisional’ Domain. Components are organized under the Domain structure, which is critical to making microservices easy to find and share and reducing redundant coding. 


Microservices are changing the way we develop, build, and deploy software. While solving many problems, microservices are also creating new challenges around tracking and versioning our overall software supply chain.

New methods and best practice strategies for microservice version management are needed to simplify the complexities of cloud-native development. DeployHub is one such solution. Its microservice catalog with built-in microservice versioning is designed to create a unified view of all your services, who uses them, who owns them and where they are running.