Last modified July 19, 2021

Workload Cluster release versions

Our workload cluster (formerly: tenant cluster) releases define the capabilities of the clusters you create in your installations. Here we explain the semantics of our versioning and give details on workload cluster release on certain providers.

Introduction

Throughout the lifecycle of a cluster, you first have the option to select a workload cluster release when creating the cluster. Later you are likely to upgrade the cluster from release to release. Understanding the differences of Major, Minor and Patch releases and their impact is crucial.

Each workload cluster release bundles a stack of components with their specific versions. The workload cluster release itself is distinguished by the provider it is made for (AWS, Azure, or KVM) and the version number, which follows the Semver standard.

We test workload cluster releases as a whole. To upgrade a component to a newer version, the entire cluster is upgrade to a new workload cluster release. This is our best way to ensure that all components in the cluster interoperate well.

Conventions around workload cluster release versioning

The Semver standard specifies version numbers in the form of Major.Minor.Patch.

Each new workload cluster release defines a set of changes with regard to exactly one previous workload cluster release. The nature or impact of the changes influence the version number of the new release.

Major version

The Kubernetes project provides the most important component of our workload clusters. So we align our workload cluster release versioning with the Kubernetes releases.

Convention: For each new minor Kubernetes release we provide a new major workload cluster release version.

The following table shows which of our major releases contain which Kubernetes release.

Workload cluster release version Kubernetes version Availability
12.x.x 1.17.x Available
13.x.x 1.18.x Available
14.x.x 1.19.x Available
15.x.x 1.20.x Available for AWS and Azure

We test every new major workload cluster release, bringing a new Kubernetes minor release, against the CNCF conformance test suite. Every workload cluster release, from patch to major, also undergoes automated integration testing.

A major workload cluster release may contain more important changes, apart from a new Kubernetes release. Check the Details about releases and features section for more information.

Minor version

We increase (bump) the minor version number when a workload cluster release adds new functionality, while maintaining the functionality of the stack as it was in the previous version. This can include minor upgrades of third party components, except for Kubernetes.

Patch version

We use patch releases to publish bug fixes, security fixes, or to make changes to the observability while maintaining the given functionality of the stack. This can include any sort of patch upgrades of third party components.

Lifecycle

For every provider, we maintain two different major versions of workload cluster releases at the same time, which means that you have two different Kubernetes minor versions to chose from.

With our development of new functionality we focus on our latest major version. The older major version is mostly maintained to fix security issues and stability problems.

Old workload cluster release get deprecated when replaced by newer ones. After deprecation, and once no longer in use by any customer, a workload cluster release gets archived, which means that it is no longer accessible to you.

Deprecation

Once we provide a new workload cluster release, be it major, minor, or patch, we usually deprecate an older version.

  • When we release a new major version, we deprecate all remaining workload cluster release in the oldest major version (to have only two major versions maintained).
  • When releasing a new minor or patch version, we deprecate the previous version. For example, when v12.1.0 comes out, the previous version v12.0.1 gets deprecated.

Once deprecated, you can still continue to use the workload cluster release with existing clusters. In addition, as long as you have at least one cluster in your installation running the deprecated release, you can also create new clusters using that release. This allows you to create test clusters to test an upgrade from that release.

Inspecting workload cluster releases

You have several options to inspect workload cluster release details:

  • We announce new workload cluster releases in your Slack support channel. In each announcement, you will find a link to the corresponding release notes in our changes and releases section here on the docs site, where you also find comprehensive release notes.

  • In the web UI, the cluster overview and the cluster details page show the release version number of the workload cluster. In the cluster details page you can click the release version number to get more information about a workload cluster release. Additionally, the web UI will soon provide more ways to browse workload cluster releases and inspect changes between versions.

  • In gsctl, our command line interface, commands like gsctl list clusters and gsctl show cluster reveal the release version number of an existing cluster. To get information on all available releases, use the gsctl list releases command. The command gsctl show release gives you more details on a specific workload cluster release.

  • The Giant Swarm REST API provides an endpoint to list all workload cluster releases with their details.

Details about workload cluster releases and features

Node pools

Node pools were introduced by the following workload cluster releases:

  • AWS: **10.0.0 **.

  • Azure: **13.0.0 **.

Preinstalled and optional Apps

Depending on your provider (AWS, Azure, or KVM), the apps NGINX IC, External DNS, and Cert Manager may be preinstalled, optional, or not available (n/a).

Preinstalled apps are installed by default upon cluster creation. Optional apps can be installed from App Catalogs. In releases where they are not preinstalled, n/a apps (e.g. External DNS in certain releases) are currently not available to be installed as an optional app.

Workload cluster release version NGINX IC External DNS Cert Manager
AWS v10.x.x+ optional preinstalled preinstalled
AWS legacy preinstalled n/a optional
Azure v12.x.x+ optional preinstalled optional
Azure legacy preinstalled preinstalled optional
KVM 12.2.x+ optional n/a optional
KVM legacy preinstalled n/a optional

Further reading

  • Cluster upgrades explains how upgrades work and suggests some best practices to keep a cluster ready to upgrade.