For longtime followers of Lagoon, you'll know we've been working towards Kubernetes 1.22 support ever since it was released 9 months ago.

Whilst Kubernetes sets a fairly aggressive development and release pace (three releases per year), the major cloud providers make these releases available on a different schedule, which often lags behind the upstream release by a few months.

See a few here:

• Google Kubernetes Engine
• Azure Kubernetes Service
• Elastic Kubernetes Service

What is most important is noting when your provider will auto-upgrade your cluster to a new version of Kubernetes though. Most Kubernetes releases are relatively smooth to upgrade between, but occasionally there are more significant Kubernetes releases that are always tricky to navigate as they usually come with a raft of deprecations. These are usually communicated well in advance, but can still cause issues, especially in a code base with as many moving parts as Lagoon.

Thankfully, the Kubernetes API is extremely well documented, and the team publishes a Deprecated API Migration Guide for us to follow. When an API is deprecated, it is usually because the version of that API has incremented, either to a beta, or stable release. Occasionally, though, an API that we were using may be removed from Kubernetes.

For every API that we use, we have to assess whether the deprecation impacts us:

• is it a simple name change? (i.e. coordination.k8s.io/v1beta1 renames to coordination.k8s.io/v1)
• is it a name change with some spec changes? (i.e. in authorization.k8s.io/v1 API version, spec.group was renamed to spec.groups
• has that API (or part of it) been removed from Kubernetes? (i.e. PodSecurityPolicy in Kubernetes 1.25)
• is it a larger change that requires a rewrite (i.e. most of the deprecated APIs that Lagoon uses 🤦)

We've gone through all the various components of Lagoon with a fine-toothed comb (and the aid of the built-in deprecation warnings) to make sure that all references to these deprecated APIs have been updated for the replacements. This includes all the Helm charts used to deploy Lagoon, Lagoon projects running on Lagoon, and the third-party services that Lagoon utilizes. It also includes some code rewrites in the controllers and operators that Lagoon deploys.

As of lagoon-core release 1.0.0, this work has been completed! All the latest releases of the Lagoon Helm charts are fully Kubernetes 1.22 (and also 1.23!) compatible. We have taken some additional steps to ensure future compatibility, such as matrix testing versions 1.21,1.22,1.23 and 1.24 for releases, and running a range of test clusters prior to releases, and marking the Lagoon components as not supporting Kubernetes <1.19 - as that is when a number of the replacement APIs that we have migrated to were first introduced.

To anybody running a pre-1.0.0 version of Lagoon on their <1.21 cluster, we would encourage you to upgrade to 1.22 ahead of time.

Kubernetes has introduced a number of webhooks that will automatically update any resources to be compatible with Kubernetes 1.22, and the cluster will upgrade safely to 1.22. However, subsequent Helm chart upgrades may fail, as they are operating on the pre-updated state of those resources, which are no longer valid Kubernetes objects (confusing, huh?).

There is a fix to this, thankfully, if you've already upgraded, or been upgraded and see this error:

  Error: UPGRADE FAILED: current release manifest contains removed kubernetes api(s) for this kubernetes version and it is therefore unable to build the kubernetes objects for performing the diff. error from kubernetes: unable to recognize "": no matches for kind "PriorityClass" in version "scheduling.k8s.io/v1beta1"

The Helm plugin https://github.com/helm/helm-mapkubeapis was designed to resolve exactly this issue, and comes preloaded with the necessary resource mappings to update for any version of Kubernetes! We can testify that it works perfectly :cough:

As always, feel free to reach out to the Lagoon team if you've got any questions - you can even find us in our shiny new Discord Server