sigs.k8s.io/gateway-api@v1.0.0/geps/gep-922.md (about)

     1  # GEP-922: Gateway API Versioning
     2  
     3  * Issue: [#922](https://github.com/kubernetes-sigs/gateway-api/issues/922)
     4  * Status: Standard
     5  
     6  !!! note
     7      Although this GEP serves as a reference for how we developed the Gateway API
     8      versioning model, it is not meant to be the current source of truth.
     9      Instead, please refer to our [official Versioning
    10      Policy](/concepts/versioning) for the most up-to-date guidelines.
    11  
    12  ## TLDR
    13  Each Gateway API release will be represented by a bundle version that represents
    14  that specific combination of CRDs, API versions, and validating webhook. To
    15  enable experimental fields, future releases of the API will include standard and
    16  experimental CRD tracks. Users will be able to access experimental features by
    17  installing the experimental CRDs. A cluster can contain either an experimental
    18  or standard CRD for any resource at a given time.
    19  
    20  ## Goals
    21  Provide a path for implementations to support:
    22  
    23  * Users should have a predictable experience when interacting with Gateway API.
    24  * The API should be able to continue to safely evolve, including:
    25      * Loosening validation
    26      * Transitioning required fields to optional
    27      * Adding new fields at an experimental stability level
    28  
    29  ## Introduction
    30  This GEP details how we should approach future releases of Gateway API. This is
    31  intended as another step towards building consensus. Once merged, it will be
    32  considered implemented once this content is fully documented.
    33  
    34  ## Version Terminology
    35  Gateway API has two related but different versioning schemes:
    36  
    37  ### 1. API Versions (ex: v1alpha2)
    38  Each API version provides a unique way to interact with the API. Significant
    39  changes such as removing or renaming fields will be represented here.
    40  
    41  ### 2. Bundle Versions (ex: v0.4.0)
    42  Bundle versions are broader in scope. They use semantic versioning and include
    43  the following:
    44  
    45  * API Types/CRDs
    46  * Validating Webhook
    47  
    48  Each bundle may include multiple API versions, potentially introducing new ones
    49  and/or removing old ones as part of a new bundle.
    50  
    51  ## Limitations of Webhook and CRD Validation
    52  CRD and webhook validation is not the final validation i.e. webhook is “nice UX”
    53  but not schema enforcement. This validation is intended to provide immediate
    54  feedback to users when they provide an invalid configuration, but can not
    55  completely be relied on because it:
    56  
    57  * Is not guaranteed to be present or up to date in all clusters.
    58  * Will likely never be sufficient to cover all edge cases.
    59  * May be loosened in future API releases.
    60  
    61  ## Persona Requirements
    62  When implementing or using Gateway API, each persona has a unique set of
    63  responsibilities to ensure we're providing a consistent experience.
    64  
    65  ### API Authors:
    66  * MUST provide conversion between API versions (excluding experimental fields),
    67    starting with v1alpha2.
    68  * MAY include the following changes to an existing API version with a new bundle
    69   **patch** version:
    70      * Clarifications to godocs
    71      * Updates to CRDs and/or code to fix a bug
    72      * Fixes to typos
    73  * MAY include the following changes to an existing API version with a new bundle
    74    **minor** version:
    75      * Everything that is valid in a patch release
    76      * New experimental API fields or resources
    77      * Loosened validation
    78      * Making required fields optional
    79      * Removal of experimental fields
    80      * Removal of experimental resources
    81      * Graduation of fields or resources from experimental to standard track
    82  * MAY introduce a new **API version** with a new bundle minor version, which may
    83    include:
    84      * Everything that is valid in a minor release
    85      * Renamed fields
    86      * Anything else that is valid in a new Kubernetes API version
    87      * Removal/tombstoning of beta fields
    88  * MAY release a new major bundle version (v1.0) as part of graduating the API to
    89    GA and releasing a new API version.
    90  
    91  Note that each new bundle version, no matter how small, may include updated
    92  CRDs, webhook, or both. Implementations may read annotations on Gateway API CRDs
    93  (defined below) to determine the version and channel of CRDs that have been
    94  installed in the cluster.
    95  
    96  ### Implementers:
    97  * MUST handle fields with loosened validation without crashing
    98  * MUST handle fields that have transitioned from required to optional without
    99    crashing
   100  * MUST NOT rely on webhook or CRD validation as a security mechanism. If field
   101    values need to be escaped to secure an implementation, both webhook and CRD
   102    validation can be bypassed and cannot be relied on. Instead, implementations
   103    should implement their own escaping or validation as necessary. To avoid
   104    duplicating work, Gateway API maintainers are considering adding a shared
   105    validation package that implementations can use for this purpose. This is
   106    tracked by [#926](https://github.com/kubernetes-sigs/gateway-api/issues/926).
   107  
   108  ### Installers:
   109  * MUST install a full Gateway API bundle, with matching CRD and webhook
   110    versions.
   111  
   112  ## Adding Experimental Fields
   113  Over time, it will be useful to add experimental fields to the API. In upstream
   114  Kubernetes, those would generally be guarded with feature gates. With Gateway
   115  API we will accomplish by releasing experimental versions of our CRDs.
   116  
   117  With this approach, we achieve a similar result. Instead of using feature gates
   118  and validation to prevent fields from being set, we just release separate CRDs.
   119  Once the API reaches beta, each bundle release can include 2 sets of CRDs,
   120  standard and experimental.
   121  
   122  New fields will be added to the experimental set of CRDs first, and may graduate
   123  to the standard set of APIs later. Experimental fields will be marked with the
   124  `+experimental` annotation in Go type definitions. Gateway API CRD generation
   125  will exclude these fields from standard set of CRDs. Experimental fields may be
   126  removed from the API. Due to the experimental nature of these CRDs, they are not
   127  recommended for production use.
   128  
   129  If experimental fields are removed or renamed, the original field name should be
   130  removed from the go struct, with a tombstone comment ensuring the field name
   131  will not be reused.
   132  
   133  Each CRD will be published with annotations that indicate their bundle version
   134  and channel:
   135  
   136  ```
   137  gateway.networking.k8s.io/bundle-version: v0.4.0
   138  gateway.networking.k8s.io/channel: standard|experimental
   139  ```
   140  
   141  ## Alternatives Considered
   142  ### 1. Use Webhook to Implement Feature Gates
   143  This option would involve using the webhook to prevent experimental fields from
   144  being set unless the corresponding feature gate was enabled. This would make use
   145  of the existing Kubernetes feature gate tooling.
   146  
   147  This approach would be familiar to Kubernetes users, but would put a lot of
   148  emphasis on the webhook. It would require webhook versioning to be precisely in
   149  line with the CRDs, and edge cases during the upgrade process could get rather
   150  messy.
   151  
   152  ### 2: Reuse Alpha API versions
   153  With this approach, we would only allow the use of these fields when using the
   154  alpha API.
   155  
   156  To simplify conversion, new fields will be added to all versions of the API,
   157  with some key exceptions:
   158  
   159  * New fields will be added with an `alpha` prefix to beta and GA API versions.
   160  * Webhook validation would ensure that new fields will only be writable when
   161    using alpha API versions.
   162  * New fields may be removed without replacement while they are still considered
   163    alpha.
   164  
   165  An alpha API field could graduate to beta in the subsequent minor release of the
   166  API. That process would involve:
   167  
   168  * Loosening webhook validation to allow writes to the field with beta API
   169    versions.
   170  * Removing the alpha prefix from the field name in the beta API Changing the
   171    alpha prefix to a beta prefix in the GA API.
   172  
   173  A beta API field could graduate to GA in the subsequent minor release of the
   174  API. That process would involve:
   175  
   176  * Loosening webhook validation to allow writes to the field with GA API
   177    versions.
   178  * Removing the beta prefix from the field name in the GA API.
   179  
   180  This is potentially the most complex of all the options presented. It would
   181  effectively require us to consistently maintain an alpha API version. Of all the
   182  options presented, this is probably the most likely to confuse users and
   183  implementers of the API.