This document describes how KEDA handles deprecations and breaking changes and should provide clarity to KEDA end-users on what to expect when upgrading to a new version of KEDA.
If you are interested in the current open deprecations, we recommend checking our GitHub Discussions or the open breaking changes.
KEDA follows the deprecation strategy of Kubernetes and is allowed to make breaking changes in minor versions after a deprecation period.
The KEDA runtime, which consists of the operator and metric server, will provide support on the deprecated features for 6 months (currently the equivalent of 2 releases) after the deprecation was announced. In the following release, the feature will be removed.
Depending on the area of the change, KEDA might not wait the above mentioned deprecation period to introduce a breaking change because one of its dependencies such as Kubernetes or scaler dependencies. However, these are the only exceptions to the rule.
Our custom resource definitions (CRDs) have a separate versioning scheme than the KEDA runtime given they have an apiVersion. For this, we follow the official Kubernetes API versioning policy.
KEDA is allowed to make breaking changes to the CRDs, when a new apiVersion is introduced.
New features in KEDA can be marked as experimental which means end-users can use them; but they are not supported by the KEDA team yet. KEDA can make any breaking changes to experimental features without any deprecation period.
Experimental features are only available for evaluation and not recommended for production use.
An overview of experimental features will become available in the documentation and graduation to stable features are communicated in the release notes.
Until KEDA introduces a versioning scheme for autoscaling triggers, it is not allowed to make breaking changes for triggers.
However, it is allowed to introduce new triggers and features in the same apiVersion.
The only exceptions to this rule is when KEDA maintainers decide to remove a scaler as part of our scaler governance. In this case, the scaler will be removed after the above mentioned deprecation period of 2 releases/6 months. The reason for being able to remove scalers is that they are no longer maintained and thus no longer supported.
The Helm charts that KEDA provides has a separate release & version lifecycle. They follow Semantic Versioning but specifically around the Helm charts and is versioned independently from the KEDA runtime.
As per our Kubernetes compatibility policy, we provide support for Kubernetes N-2.
This means that a minor version upgrade of KEDA is backwards-compatible with Kubernetes N-2, but might remove support for an older version.
This kind of change will be announced in the release notes and enforced in our Helm charts.
You can find an overview of our compatibility matrix in our Kubernetes compatibility documentation.
The only exception to this rule is when we are forced to make a breaking change that is enforced by Kubernetes and we need to introduce it sooner.
A breaking change is a change that is not backwards-compatible and requires end-users to take manual action to migrate or lose existing functionality.
When contributors want to introduce a new approach, they are allowed to do so without breaking changes. This means that the new approach will live next to the deprecated functionality during the deprecation period.
Every occasion of this must provide warning(s) in the KEDA logs to make end-users aware of the change so they can decide whether to migrate to the new approach - Either by using the new functionality in the next minor version or by migrating to the new approach when the next major version was released.
Every deprecation must follow our process described below.
When introducing a new deprecation, it must comply with the following rules:
- Every deprecation must be announced in the release notes and will be highlighted in the upcoming release(s)
- Every deprecation must have a warning in the KEDA logs to create awareness
- Every deprecation must be documented on
keda.shand explicitly mention timelines- We recommend using this as inspiration:
# DEPRECATED: This parameter is deprecated as of KEDA v2.10 in favor of {replacement} and will be removed in version 2.12
- We recommend using this as inspiration:
- Every deprecation must have a representing issue that is used for tracking breaking changes for our upcoming major version.
- Because of that, it must be labeled with
breaking-change - A label will be added to indicate the version in which it will be removed, example
removal:keda-v2.12.
- Because of that, it must be labeled with
- Every deprecation must be announced on GitHub Discussions (example)
- It should explain when the deprecation takes effect, what the impact is, how to migrate and when it will be removed.