Skip to content

Commit

Permalink
Phasing out Beta from Versioning Guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@robscott
robscott committed Oct 3, 2023
1 parent 18506b7 commit 84a6d75
Show file tree
Hide file tree
Showing 2 changed files with 129 additions and 106 deletions.
15 changes: 10 additions & 5 deletions geps/gep-922.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,24 @@
* Issue: [#922](https://github.com/kubernetes-sigs/gateway-api/issues/922)
* Status: Standard

!!! note
Although this GEP serves as a reference for how we developed the Gateway API
versioning model, it is not meant to be the current source of truth.
Instead, please refer to our [official Versioning
Policy](/concepts/versioning) for the most up-to-date guidelines.

## TLDR
Each Gateway API release will be represented by a bundle version that represents
that specific combination of CRDs, API versions, and validating webhook. To
enable experimental fields, future releases of the API will include standard and
experimental CRD tracks. Users will be able to access experimental features by
installing the experimental CRDs. A cluster can contain either an experimental
or standard CRD for any resource at a given time.

or standard CRD for any resource at a given time.

## Goals
Provide a path for implementations to support:

* Users should have a predictable experience when interacting with Gateway API.
* Users should have a predictable experience when interacting with Gateway API.
* The API should be able to continue to safely evolve, including:
* Loosening validation
* Transitioning required fields to optional
Expand Down Expand Up @@ -123,7 +128,7 @@ recommended for production use.

If experimental fields are removed or renamed, the original field name should be
removed from the go struct, with a tombstone comment ensuring the field name
will not be reused.
will not be reused.

Each CRD will be published with annotations that indicate their bundle version
and channel:
Expand All @@ -146,7 +151,7 @@ messy.

### 2: Reuse Alpha API versions
With this approach, we would only allow the use of these fields when using the
alpha API.
alpha API.

To simplify conversion, new fields will be added to all versions of the API,
with some key exceptions:
Expand Down
220 changes: 119 additions & 101 deletions site-src/concepts/versioning.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,59 +2,102 @@

## Overview
Each new release of Gateway API is defined with a "bundle version" that
represents the Git tag of a release, such as v0.4.0. This contains the
represents the Git tag of a release, such as v0.8.0. This contains the
following:

* API Types (Go bindings for the resources)
* CRDs (Kubernetes definitions of the resources)
* Validating Webhook

### API Versions (e.g. v1alpha2, v1beta1)
Within Gateway API, API versions are primarily used to indicate the stability of
a resource. For example, if a resource has not yet graduated to beta, it is
still possible that it could either be removed from the API or changed in
backwards incompatible ways. For more information on API versions, refer to the
[full Kubernetes API versioning
documentation](https://kubernetes.io/docs/reference/using-api/#api-versioning).

![Lifecycle of New Gateway API Resources](/images/lifecycle-new-resources.png)
<!-- Source: https://docs.google.com/presentation/d/1sfZTV-vlisDUIie_iK_B2HqKia_querT6m6T2_vbAk0/edit -->

### Release Channels (e.g. Experimental, Standard)
Gateway API provides 2 release channels: an Experimental one and a Standard one.
* Validating Webhook (Will be deprecated in v1.0 release)

### Release Channels
Release channels are used to indicate feature stability within Gateway API. All
new features and resources start in the Experimental release channel. From that
point, these may graduate to the Standard release channel or be dropped from the
API entirely.

The following diagram provides a high level overview of the lifecycle of a
feature or resource proposed by a new [GEP](/geps/overview/) (enhancement
proposal) in Gateway API:

```mermaid
flowchart TD
0([Implementable GEP]) --> A
A>Experimental Channel] --> B([Widely used and working well?])
B -->|Yes| C>Standard Channel]
B -->|No| D([Could Changes Help?])
D -->|Yes| E([Adjust and try again])
D -->|No| F>Remove From API]
E -->A
style A fill:#eeb
style C fill:#beb
style F fill:#ebb
```

The Standard release channel includes:

* Resources that have graduated to beta
* All fields that have graduated to standard and are no longer considered
experimental
* Resources that have graduated to Beta or GA API Versions (note that Beta API
versions are being phased out in Gateway API)
* All fields that have graduated to Standard from the Experimental Channel

The Experimental release channel includes everything in the Standard release
channel, plus:

* Alpha API resources
* New fields that are considered experimental and have not yet graduated to the
standard channel
* Resources with Alpha API Versions
* All new fields before they graduate to Standard Channel

![Release Channel Overlap](/images/release-channel-overlap.svg)
<!-- Source: https://docs.google.com/presentation/d/1sfZTV-vlisDUIie_iK_B2HqKia_querT6m6T2_vbAk0/edit -->

Release channels are used to indicate feature stability within Gateway API. For
example, even if a resource has already graduated to beta, we need a way to test
out new fields and features before committing to their long term stability. With
upstream Kubernetes APIs, this is accomplished with [feature
gates](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/).
Unfortunately, CRDs do not have a similar concept yet.

Instead of trying to recreate feature gates in this project, we've introduced
release channels. Starting in v0.5.0, all new fields and features will start in
the Experimental release channel. From that point, these may graduate to the
Standard release channel or be dropped from the API entirely. See
[GEP-922](/geps/gep-922) for a more detailed discussion of this approach to new
fields and features.

![Lifecycle of New Gateway API Fields](/images/lifecycle-new-fields.svg)
<!-- Source: https://docs.google.com/presentation/d/1sfZTV-vlisDUIie_iK_B2HqKia_querT6m6T2_vbAk0/edit -->
We recommend using the "Standard" release channel by default as it will provide
a stable experience. The "Experimental" feature enables us to iterate on new
features quickly but may include breaking changes and should not be relied on
in production environments.

### API Versions
Upstream Kubernetes APIs have 3 levels of stability, denoted by alpha, beta, and
GA API versions. In Gateway API, we've narrowed this down to 2 levels of
stability, expressed by our release channels as described above.

In general, this means that when resources graduate from the Experimental
channel to the Standard Channel, they'll also be graduating from an Alpha API
Version (v1alpha2) to a GA API Version (v1).

#### Rationale
We're phasing out beta for the following reasons:

1. In most cases there are effectively two levels of API stability - installed
by default (stable), and alpha/experimental (unstable). It's not obvious
what value an intermediate (Beta) state would have for Gateway API.
2. The further we separate the "stable" and "experimental" APIs, the longer it
takes to get meaningful feedback on new features.
3. Each unique API version we maintain comes with significant additional cost
for users, implementers, and maintainers.

#### Beta
Although some Gateway API resources already received a Beta API version when
they graduated to the Standard Channel, that will not be the case for any
additional resources. All future resources that graduate to Standard Channel
will include a v1 API version as part of that process.

The resources that already have a beta API version (v1beta1) are:

* HTTPRoute
* Gateway
* GatewayClass
* ReferenceGrant

In the upcoming v1.0 release, HTTPRoute, Gateway, and GatewayClass will all
graduate to a GA API Version (v1).

ReferenceGrant is a special case since it is in the process of [transitioning
into an upstream Kubernetes
API](https://github.com/kubernetes/enhancements/issues/3766) that is owned by
[sig-auth](https://github.com/kubernetes/community/blob/master/sig-auth/README.md).
Until that is resolved, it is likely that ReferenceGrant will be effectively
frozen as beta in Gateway API. When it is widely available as a built-in
Kubernetes API, we will likely remove it from the Standard Channel of Gateway
API.

## Version Indicators
Each CRD will be published with annotations that indicate their bundle version
Expand All @@ -67,74 +110,61 @@ gateway.networking.k8s.io/channel: standard|experimental

## What can Change
When using or implementing this API, it is important to understand what can
change across API versions.
change across bundle versions.

### Patch version (e.g. v0.4.0 -> v0.4.1)
* Clarifications to godocs
* Updates to CRDs and/or code to fix a bug
* Conformance test fixes
* Additional conformance test coverage for existing features
* Fixes to typos
* API Spec:
* Clarifications
* Correcting typos
* Bug fixes:
* Correcting validation
* Fixes to release process or artifacts
* Conformance tests:
* Fixes for existing tests
* Additional conformance test coverage for existing features

### Minor version (e.g. v0.4.0 -> v0.5.0)
* Everything that is valid in a patch release
* New experimental API fields or resources
* Changes to recommended conditions or reasons in status
* Loosened validation
* Making required fields optional
* Removal of experimental fields
* Removal of experimental resources
* Graduation of fields or resources from experimental to standard track
* Changes to conformance tests to match spec updates
* Introduction of a new **API version**, which may also include:
* Renamed fields
* Anything else that is valid in a new Kubernetes API version
* Removal/tombstoning of beta fields
* Removal of an API resource following [Kubernetes deprecation
* Experimental Channel:
* Adding new API fields or resources
* Breaking changes for existing API fields or resources
* Removing API fields or resources without prior deprecation
* Standard Channel:
* Graduation of fields or resources from Experimental to Standard Channel
* Removal of an API resource following [Kubernetes deprecation
policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/)
* All Channels:
* Changes to recommended conditions or reasons in status
* Loosened validation (including making required fields optional)
* Changes to conformance tests to match spec updates
* Introduction of a new API version which may include renamed fields or
anything else that is valid in a [new Kubernetes API
version](https://kubernetes.io/docs/reference/using-api/#api-versioning)

### Major version (e.g. v0.x to v1.0)
* There are no API compatibility guarantees when the major version changes.

## Graduation Criteria
For a resource, field, or feature to graduate from Experimental to Standard, it
must meet the following criteria:

### Resources

#### Alpha -> Beta
A resource to graduate from alpha to beta must meet the following criteria:

* Implemented by several implementations.
* Conformance test framework is in place, with some coverage of basic
functionality.
* Validation is well thought out.
* Most of the API surface is being exercised by users.
* Approval from subproject owners + KEP reviewers.

#### Beta -> GA

A resource to graduate from beta to GA must meet the following criteria:

* Almost all of the fields and behavior have conformance test coverage.
* Full conformance test coverage.
* Multiple conformant implementations.
* Widespread implementation and usage.
* At least 6 months of soak time as a beta API.
* At least 6 months of soak time as an alpha API.
* No significant changes for at least 1 minor release and 3 months.
* Approval from subproject owners + KEP reviewers.

### Fields

#### Experimental -> Standard
As described above, field level stability is layered on top of beta and GA
resources (no fields in alpha resources can be considered standard). The
requirements for a field to graduate from experimental to standard depend on the
API version of the resource it is a part of. For a field to be considered
standard, it needs to meet the same criteria of the resource it is contained in.
## Supported Versions
This project aims to provide support for a wide range of Kubernetes versions with
consistent upgrade experiences across versions. To accomplish that, we commit to:

If a resource has graduated to beta, an experimental field must meet all of the
beta graduation criteria before graduating to standard. Similarly, if a resource
has graduated to GA, a field must meet all of the beta and GA graduation
criteria. There is one slight variation here, instead of 6 months of soak time
as a beta API, a field graduating to standard requires 6 months of soak time as an
experimental field.
1. Support a minimum of the most recent 5 Kubernetes minor versions.
2. Ensure that all Standard Channel changes between v1beta1 and v1 are fully
compatible and convertible.
3. Take every possible effort to avoid introduction of a conversion webhook. If
a conversion webhook needs to be introduced, it will be supported for the
lifetime of the API, or at least until an alternative is available.

## Out of Scope
### Unreleased APIs
Expand All @@ -148,15 +178,3 @@ this project.
We do not provide stability guarantees for source code imports. The Interfaces
and behavior may change in an unexpected and backwards-incompatible way in any
future release.

## Supported Versions

This project aims to provide support for a wide range of Kubernetes versions with
consistent upgrade experiences across versions. To accomplish that, we commit to:

1. Support a minimum of the most recent 5 Kubernetes minor versions.
2. Ensure that all standard channel changes between v1beta1 and v1 are fully
compatible and convertible.
3. Take every possible effort to avoid introduction of a conversion webhook. If
a conversion webhook needs to be introduced, it will be supported for the
lifetime of the API, or at least until an alternative is available.

0 comments on commit 84a6d75

Please sign in to comment.