Antrea versions are expressed as
x is the major version,
the minor version, and
z is the patch version, following Semantic Versioning
The major version for Antrea is currently 0. In particular, this means that the Antrea APIs are still evolving at a pretty fast pace and that some features which we consider important for a K8s network plugin have not been implemented yet or have not reached the General Availability (GA) stability level. We have not yet established a definitive list of features that should be GA before we switch to a major version number of 1, but here are a few important features that are likely to be included.
security.antrea.tanzu.vmware.comAPI group should be stable and in version
Unlike minor releases, patch releases should not contain miscellaneous feature additions or improvements. No incompatibilities should ever be introduced between patch versions of the same minor version. API groups / versions must not be introduced or removed as part of patch releases.
Patch releases are intended for important bug fixes to recent minor versions, such as addressing security vulnerabilities, fixes to problems preventing Antrea from being deployed & used successfully by a significant number of users, severe problems with no workaround, and blockers for products (including commercial products) which rely on Antrea.
When it comes to dependencies, the following rules are observed between patch versions of the same Antrea minor versions:
For every Antrea minor release, the stability level of supported features may be
Beta or from
GA). Refer to the the
CHANGELOG for information about feature stability level for each release. For
features controlled by a feature gate, this information is also present in a
more structured way in feature-gates.md.
New Antrea minor releases are currently shipped every 6 to 8 weeks. This fast release cadence enables us to ship new features quickly and frequently. It may change in the future. Compared to deploying the top-of-tree of the Antrea master branch, using a released version should provide more stability guarantees:
Antrea maintains release branches for the two most recent minor releases
release-0.11 branches are maintained until Antrea
0.12 is released). As part of this maintenance process, patch versions are
released as frequently as needed, following these
guidelines. With the current release
cadence, this means that each minor release receives approximately 3 months of
patch support. This may seem short, but was done on purpose to encourage users
to upgrade Antrea often and avoid potential incompatibility issues. In the
future, we may reduce our release cadence for minor releases and simultaneously
increase the support window for each release.
Our goal is to support "graceful" upgrades for Antrea. By "graceful", we notably mean that there should be no significant disruption to data-plane connectivity nor to policy enforcement, beyond the necessary disruption incurred by the restart of individual components:
In particular, it should be possible to upgrade Antrea without compromising enforcement of existing network policies for both new and existing Pods.
In order to achieve this, the different Antrea components need to support version skew.
The supported version skew means that we only recommend Antrea upgrades to a new release up to 4 minor versions newer. For example, a cluster using 0.10 can be upgraded to one of 0.11, 0.12, 0.13 or 0.14, but we discourage direct upgrades to 0.15 and beyond. With the current release cadence, this provides a 6-month window of compatibility. If we reduce our release cadence in the future, we may revisit this policy as well.
When directly applying a newer Antrea YAML manifest, as provided for each release, there is no guarantee that the Antrea Controller will be upgraded first. In practice, the Controller would be upgraded simultaneously with the first Agent(s) to be upgraded by the rolling update of the Agent DaemonSet. This may create some transient issues and compromise the "graceful" upgrade. For upgrade scenarios, we therefore recommend that you "split-up" the manifest to ensure that the Controller is upgraded first.
Each Antrea minor release should support maintained K8s releases at the time of release (3 up to K8s 1.19, 4 after that). For example, at the time that Antrea 0.10 was released, the latest K8s version was 1.19; as a result we guarantee that 0.10 supports at least 1.19, 1.18 and 1.17 (in practice it also supports K8s 1.16).
Antrea follows a similar policy as Kubernetes for metrics deprecation.
Alpha metrics have no stability guarantees; as such they can be modified or deleted at any time.
Stable metrics are guaranteed to not change; specifically, stability means:
Eventually, even a stable metric can be deleted. In this case, the metric must be marked as deprecated first and the metric must stay deprecated for at least one minor release. The CHANGELOG must announce both metric deprecations and metric deletions.
# HELP some_counter this counts things # TYPE some_counter counter some_counter 0
# HELP some_counter (Deprecated since 0.10.0) this counts things # TYPE some_counter counter some_counter 0
In the future, we may introduce the same concept of hidden metric as K8s, as an additional part of the metric lifecyle.
The Antrea APIs are built using K8s (they are a combination of CustomResourceDefinitions and aggregation layer APIServices) and we follow the same versioning scheme as the K8s APIs and the same deprecation policy.
Other than the most recent API versions in each track, older API versions must be supported after their announced deprecation for a duration of no less than:
This also applies to the
controlplane API. In particular, introduction and
removal of new versions for this API must respect the "graceful" upgrade
(which is exposed using the aggregation layer) is often referred to as an
"internal" API as it is used by the Antrea components to communicate with each
other, and is usually not consummed by end users, e.g. cluster admins. However,
this API may also be used for integration with other software, which is why we
abide to the same deprecation policy as for other more "user-facing" APIs
(e.g. Antrea-native policy CRDs).
K8s has a moratorium on the removal of API object versions that have been persisted to storage. At the moment, none of Antrea APIServices (which use the aggregation layer) persist objects to storage. So the only objects we need to worry about are CustomResources, which are persisted by the K8s apiserver. For them, we adopt the following rules:
deprecatedfield must be used for CRDs to indicate that a particular version of the resource has been deprecated.