sigs.k8s.io/gateway-api@v1.0.0/site-src/concepts/versioning.md (about) 1 # Versioning 2 3 ## Overview 4 Each new release of Gateway API is defined with a "bundle version" that 5 represents the Git tag of a release, such as v0.8.0. This contains the 6 following: 7 8 * API Types (Go bindings for the resources) 9 * CRDs (Kubernetes definitions of the resources) 10 * Validating Webhook (Will be deprecated in v1.0 release) 11 12 ### Release Channels 13 Release channels are used to indicate feature stability within Gateway API. All 14 new features and resources start in the Experimental release channel. From that 15 point, these may graduate to the Standard release channel or be dropped from the 16 API entirely. 17 18 The following diagram provides a high level overview of the lifecycle of a 19 feature or resource proposed by a new [GEP](/geps/overview/) (enhancement 20 proposal) in Gateway API: 21 22 ```mermaid 23 flowchart TD 24 0([Implementable GEP]) --> A 25 A>Experimental Channel] --> B([Widely used and working well?]) 26 B -->|Yes| C>Standard Channel] 27 B -->|No| D([Could Changes Help?]) 28 D -->|Yes| E([Adjust and try again]) 29 D -->|No| F>Remove From API] 30 E -->A 31 32 style A fill:#eeb 33 style C fill:#beb 34 style F fill:#ebb 35 ``` 36 37 The Standard release channel includes: 38 39 * Resources that have graduated to Beta or GA API Versions (note that Beta API 40 versions are being phased out in Gateway API) 41 * All fields that have graduated to Standard from the Experimental Channel 42 43 The Experimental release channel includes everything in the Standard release 44 channel, plus: 45 46 * Resources with Alpha API Versions 47 * All new fields before they graduate to Standard Channel 48 49  50 <!-- Source: https://docs.google.com/presentation/d/1sfZTV-vlisDUIie_iK_B2HqKia_querT6m6T2_vbAk0/edit --> 51 52 We recommend using the Standard Channel by default as it will provide a stable 53 experience. Many implementations also provide support for the Experimental 54 Channel which enables us to iterate on new features quickly. Note that this 55 channel makes no backwards compatibility guarantees and breaking changes may be 56 released at any point. 57 58 ### API Versions 59 Upstream Kubernetes APIs have 3 levels of stability, denoted by alpha, beta, and 60 GA API versions. In Gateway API, we've narrowed this down to 2 levels of 61 stability, expressed by our release channels as described above. 62 63 In general, this means that when resources graduate from the Experimental 64 channel to the Standard Channel, they'll also be graduating from an Alpha API 65 Version (v1alpha2) to a GA API Version (v1). 66 67 #### Rationale 68 We're phasing out beta for the following reasons: 69 70 1. In most cases there are effectively two levels of API stability - installed 71 by default (stable), and alpha/experimental (unstable). It's not obvious 72 what value an intermediate (Beta) state would have for Gateway API. 73 2. The further we separate the "stable" and "experimental" APIs, the longer it 74 takes to get meaningful feedback on new features. 75 3. Each unique API version we maintain comes with significant additional cost 76 for users, implementers, and maintainers. 77 78 #### Beta 79 Although some Gateway API resources already received a Beta API version when 80 they graduated to the Standard Channel, that will not be the case for any 81 additional resources. All future resources that graduate to Standard Channel 82 will include a v1 API version as part of that process. 83 84 The resources that already have a beta API version (v1beta1) are: 85 86 * HTTPRoute 87 * Gateway 88 * GatewayClass 89 * ReferenceGrant 90 91 In the upcoming v1.0 release, HTTPRoute, Gateway, and GatewayClass will all 92 graduate to a GA API Version (v1). 93 94 ReferenceGrant is a special case since it is in the process of [transitioning 95 into an upstream Kubernetes 96 API](https://github.com/kubernetes/enhancements/issues/3766) that is owned by 97 [sig-auth](https://github.com/kubernetes/community/blob/master/sig-auth/README.md). 98 Until that is resolved, it is likely that ReferenceGrant will be effectively 99 frozen as beta in Gateway API. When it is widely available as a built-in 100 Kubernetes API, we will likely remove it from the Standard Channel of Gateway 101 API. 102 103 ## Version Indicators 104 Each CRD will be published with annotations that indicate their bundle version 105 and channel: 106 107 ``` 108 gateway.networking.k8s.io/bundle-version: v0.4.0 109 gateway.networking.k8s.io/channel: standard|experimental 110 ``` 111 112 ## What Can Change 113 When using or implementing this API, it is important to understand what can 114 change across bundle versions. 115 116 ### Patch Version (e.g. v0.4.0 -> v0.4.1) 117 * API Spec: 118 * Clarifications 119 * Correcting typos 120 * Bug fixes: 121 * Correcting validation 122 * Fixes to release process or artifacts 123 * Conformance tests: 124 * Fixes for existing tests 125 * Additional conformance test coverage for existing features 126 127 ### Minor Version (e.g. v0.4.0 -> v0.5.0) 128 * Everything that is valid in a patch release 129 * Experimental Channel: 130 * Adding new API fields or resources 131 * Breaking changes for existing API fields or resources 132 * Removing API fields or resources without prior deprecation 133 * Standard Channel: 134 * Graduation of fields or resources from Experimental to Standard Channel 135 * Removal of an API resource following [Kubernetes deprecation 136 policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/) 137 * All Channels: 138 * Changes to recommended conditions or reasons in status 139 * Loosened validation (including making required fields optional) 140 * Changes to conformance tests to match spec updates 141 * Introduction of a new API version which may include renamed fields or 142 anything else that is valid in a [new Kubernetes API 143 version](https://kubernetes.io/docs/reference/using-api/#api-versioning) 144 145 ### Major Version (e.g. v0.x to v1.0) 146 * There are no API compatibility guarantees when the major version changes. 147 148 ## Graduation Criteria 149 For a resource, field, or feature to graduate from Experimental to Standard, it 150 must meet the following criteria: 151 152 * Full conformance test coverage. 153 * Multiple conformant implementations. 154 * Widespread implementation and usage. 155 * At least 6 months of soak time as an alpha API. 156 * No significant changes for at least 1 minor release and 3 months. 157 * Approval from subproject owners + KEP reviewers. 158 159 ## Supported Versions 160 This project aims to provide support for a wide range of Kubernetes versions with 161 consistent upgrade experiences across versions. To accomplish that, we commit to: 162 163 1. Support a minimum of the most recent 5 Kubernetes minor versions. 164 2. Ensure that all Standard Channel changes between v1beta1 and v1 are fully 165 compatible and convertible. 166 3. Take every possible effort to avoid introduction of a conversion webhook. If 167 a conversion webhook needs to be introduced, it will be supported for the 168 lifetime of the API, or at least until an alternative is available. 169 170 ## Out of Scope 171 ### Unreleased APIs 172 This project will have frequent updates to the main branch. There are no 173 compatibility guarantees associated with code in any branch, including main, 174 until it has been released. For example, changes may be reverted before a 175 release is published. For the best results, use the latest published release of 176 this project. 177 178 ### Source Code 179 We do not provide stability guarantees for source code imports. The Interfaces 180 and behavior may change in an unexpected and backwards-incompatible way in any 181 future release.