Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Phasing out Beta from Versioning Guide #2446

Merged
merged 1 commit into from
Oct 9, 2023
Merged

Phasing out Beta from Versioning Guide #2446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions geps/gep-922.md
View file
Open in desktop
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is !!! note intended to be as it is? I see no fancy markdown stuff being rendered.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, it's rendered in the deploy preview - this is a directive to mkdocs, not a standard Markdown one.

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
235 changes: 127 additions & 108 deletions site-src/concepts/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,59 +2,103 @@

## 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 Channel by default as it will provide a stable
experience. Many implementations also provide support for the Experimental
Channel which enables us to iterate on new features quickly. Note that this
channel makes no backwards compatibility guarantees and breaking changes may be
released at any point.

### 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.
robscott marked this conversation as resolved.
Show resolved Hide resolved

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).
robscott marked this conversation as resolved.
Show resolved Hide resolved

#### 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
robscott marked this conversation as resolved.
Show resolved Hide resolved
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 @@ -65,76 +109,63 @@ gateway.networking.k8s.io/bundle-version: v0.4.0
gateway.networking.k8s.io/channel: standard|experimental
```

## What can Change
## What Can Change
When using or implementing this API, it is important to understand what can
change across API 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

### Minor version (e.g. v0.4.0 -> v0.5.0)
change across bundle versions.

### Patch Version (e.g. v0.4.0 -> v0.4.1)
* 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/)

### Major version (e.g. v0.x to v1.0)
* 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 +179,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.