Reference Architecture versioning

[yorinasub17]

How is the Reference Architecture versioned, and how does one keep their deployed Reference Architecture up to date?

[yorinasub17]

Reference Architecture version updates can be broken up into two major categories:

• Module changes, specifically version updates to the underlying infrastructure modules and/or additional infrastructure components that are added to the Reference Architecture (e.g., if we start supporting a new component). Examples:

  • Bumping the Service Catalog Version.
  • Adding Elasticsearch as a configurable option.

• Architecture changes, where the way the Reference Architecture is organized is updated. An example of this is when the Reference Architecture was updated from snapshoted infrastructure-modules repositories per deployment, to usage of the Service Catalog.

From a semantic versioning perspective, currently the Reference Architecture is still pre-1.0 and has not reached full stability. As a part of this, Gruntwork has not solved the problem of Reference Architecture version updates. This means that for the large part updating a Reference Architecture across versions is primarily a manual process.

For the first category of changes, you can rely on the releases page of the Service Catalog to be notified of updates. For the large part, updating versions is a matter of bumping the referenced version in the terragrunt.hcl and committing the change to have the infrastructure CI/CD pipeline roll it out.

Note that the Service Catalog follows semantic versioning, and for any 0.x product, minor versions (the x in 0.x.y) are considered backward incompatible. As such, you will want to read the release notes carefully whenever you cross minor versions.

For the second category of changes, the updates will depend on how different the architecture is. For minor changes, we will publish a new release and diff in the Service Catalog for-production example. You can take a look at the changes pushed in this folder to see how the Reference Architecture evolves over minor changes.

For major changes that require significant refactoring (e.g., when the Reference Architecture was updated to use the Service Catalog), we typically publish a comprehensive guide that walks through how to make those changes to a deployed Reference Architecture. Here is an example guide we published for that change.

In the future, we plan on rolling out a product that will take care of these updates for you automatically.

Update/Nov 15, 2022: Software timelines are very hard to predict, but we plan to roll out the very first version of our upgrade tool specially for upgrading your RefArch to CIS v1.5 in Q1-2023. Shortly after, we'll begin work on a general-purpose version of the upgrade tool.