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

     1  # GEP-2162: Supported features in GatewayClass Status
     2  
     3  * Issue: [#2162](https://github.com/kubernetes-sigs/gateway-api/issues/2162)
     4  * Status: Provisional
     5  
     6  ## TLDR
     7  
     8  This GEP proposes to enhance the [GatewayClassStatus](https://github.com/kubernetes-sigs/gateway-api/blob/f2cd9bb92b4ff392416c40d6148ff7f76b30e649/apis/v1beta1/gatewayclass_types.go#L185) to include a list of Gateway API features supported by the installed GatewayClass. 
     9  
    10  ## Goals
    11  
    12  * Improve UX by enabling users to easily see what features the implementation (GatewayClass) support.
    13  
    14  * Standardize features and conformance tests names.
    15  
    16  * Automatically run conformance tests based on the supported features populated in GatewayClass status.
    17  
    18  * Provide foundation for tools to block or warn when unsupported features are used.
    19  
    20  
    21  ## Non-Goals
    22  
    23  * Validate correctness of supported features published by the implementation.
    24      Meaning we don't intend to verify whether the supported features reported by
    25      the implementation are indeed supported.
    26  
    27      However, the supported features in the status of the GatewayClass should
    28      make it very easy for any individual to run conformance tests against the
    29      GatewayClass using our conformance tooling.
    30  
    31  ## Introduction
    32  
    33  The current [GatewayClassStatus](https://github.com/kubernetes-sigs/gateway-api/blob/f2cd9bb92b4ff392416c40d6148ff7f76b30e649/apis/v1beta1/gatewayclass_types.go#L185 is only used to store conditions the controller publishes.
    34  
    35  Partnered with the [Conformance Profiles](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709.md) work, we want to:
    36  
    37  1. Improve UX by enabling users to easily see what features the implementation(GatewayClass) support.
    38  1. Standardize features and conformance tests names.
    39  1. Automatically run conformance tests based on the supported features populated in GatewayClass status.
    40  1. Potentially build tooling to block or warn when unsupported features are used (more under [Future Work](#future-work)).
    41  
    42  This doc proposes to enhance the GatewayClassStatus API so implementations could publish a list of features they support/don't support.
    43  
    44  Implementations **must** publish the supported features before Accepting the GatewayClass, or in the same operation.
    45  
    46  Implementations are free to decide how they manage this information. A common approach could be to maintain static lists of supported features or using predefined sets.
    47  
    48  Note: implementations must keep the published list sorted in ascending alphabetical order.
    49  
    50  ## API
    51  
    52  This GEP proposes API changes describes as follow:
    53  
    54  * Update the `GatewayClassStatus` struct to include a string-represented list of `SupportedFeatures`.
    55  
    56  
    57  ```go
    58  // GatewayClassStatus is the current status for the GatewayClass.
    59  type GatewayClassStatus struct {
    60      // Conditions is the current status from the controller for
    61      // this GatewayClass.
    62      //
    63      // Controllers should prefer to publish conditions using values
    64      // of GatewayClassConditionType for the type of each Condition.
    65      //
    66      // +optional
    67      // +listType=map
    68      // +listMapKey=type
    69      // +kubebuilder:validation:MaxItems=8
    70      Conditions []metav1.Condition `json:"conditions,omitempty"`
    71  
    72      // SupportedFeatures is the features the GatewayClass support.
    73      // <gateway:experimental>
    74      // +kubebuilder:validation:MaxItems=64
    75      SupportedFeatures []string `json:"supportedFeatures,omitempty"`
    76  }
    77  ```
    78  
    79  ## Understanding SupportedFeatures field
    80  
    81  Its important to define how we read the list of `SupportedFeatures` we report.
    82  
    83  We have no supported features for core features. If an implementation reports a resource name e.g `HTTPRoute` as a supportedFeature it means it supports all its core features.
    84  In other words, supporting the resource's core features is a requirement for the implementation to say that it supports the resource.
    85  
    86  For Extended/Implementation-specific features we have the supported features names.
    87  
    88  An example of a GatewayClass Status with the SupportedFeatures reported would look like:
    89  
    90  ```yaml
    91  apiVersion: gateway.networking.k8s.io/v1beta1
    92  kind: GatewayClass
    93  ...
    94  status:
    95    conditions:
    96    - lastTransitionTime: "2022-11-16T10:33:06Z"
    97      message: Handled by XXX controller
    98      observedGeneration: 1
    99      reason: Accepted
   100      status: "True"
   101      type: Accepted
   102    supportedFeatures:
   103      - HTTPRoute
   104      - HTTPRouteHostRewrite
   105      - HTTPRoutePortRedirect
   106      - HTTPRouteQueryParamMatching
   107  
   108  ```
   109  ## Standardize features and conformance tests names
   110  
   111  Before we add the supported features into our API, it is necessary to establish standardized naming and formatting conventions.
   112  
   113  ### Formatting Proposal
   114  
   115  #### Feature Names
   116  
   117  Every feature should:
   118  
   119  1. Start with the resource name. i.e HTTPRouteXXX
   120  2. Follow the PascalCase convention. Note that the resource name in the string should come as is and not be converted to PascalCase, i.e HTTPRoutePortRedirect and not HttpRoutePortRedirect.
   121  3. Not exceed 128 characters.
   122  4. Contain only letters and numbers
   123  
   124  #### Conformance test names
   125  
   126  Conformance tests file names should try to follow the the `pascal-case-name.go` format.
   127  For example for `HTTPRoutePortRedirect` - the test file would be `httproute-port-redirect.go`.
   128  
   129  We should treat this guidance as "best effort" because we might have test files that check the combination of several features and can't follow the same format.
   130  
   131  In any case, the conformance tests file names should be meaningful and easy to understand.
   132  
   133  
   134  ## Followups
   135  
   136  Before we make the changes we need to;
   137  
   138  1. Change the names of the supported features and conformance tests that don't conform with the formatting rules.
   139  
   140  
   141  ## Alternatives
   142  
   143  ### Re-using ConformanceProfiles structs
   144  
   145  We could use the same structs as we do in conformance profile object, more specifically, the [ProfileReport](https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/apis/v1alpha1/profilereport.go#LL24C6-L24C19) struct.
   146  
   147  Though it would be nice to have only one place to update, these structs seems to include much more data relevant to the conformance report but not for our use case. 
   148  
   149  That said, conformance profiles are still at experimental stage, we could explore the option to create a shared struct that will be used both for the conformance reports and for the GatewayClass status.
   150  
   151  ### Instruct users to read from the future conformance profiles report
   152  
   153  The current plan for conformance profiles is to also include centralized reporting. (more info in [gep-1709](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709.md))
   154  We could wait for this to be implemented and instruct users to read from that source to determine what features their installed GatewayClass support.
   155  
   156  However, having the supported features published in the GatewayClass Status adds the following values:
   157  
   158  * We could build a mechanism or a tool to block or warn when unsupported features are used.
   159  * Users will be able to select the GatewayClass that suits their needs without having to refer to documentation or conformance reports.
   160  
   161  This does not cover a future piece of work we want to implement which is to warn/block users from applying a Gateway API object if the installed GWC doesn't support it. (originally suggested in [#1804](https://github.com/kubernetes-sigs/gateway-api/issues/1804)). 
   162  
   163  
   164  ## References
   165  
   166  [discussion #2108](https://github.com/kubernetes-sigs/gateway-api/discussions/2108)
   167  [#1804](https://github.com/kubernetes-sigs/gateway-api/issues/1804)
   168  
   169  ## Future Work
   170  
   171  ### Research the development of an unsupported feature warning/blocking mechanism
   172  Once the GatewayClass features support are is published into the status we could look into;
   173  
   174  1. Using the supported features in the webhook to validate or block attempts to apply manifests with unsupported features.
   175  
   176      * Developing such mechanism looks like it would have to include cross-resource validation. (checking the GatewayClass while trying to apply a Route for example). This comes with a lot of caveats and we will need consider it carefully.
   177  
   178  2. Build tooling to check and warn when unsupported features are used.
   179  
   180  3. Add a table with feature name and description to document what each feature means.
   181  
   182  ### Add Gateway API Version field to the GatewayClass Status
   183  
   184  We got some feedback that it will be useful to indicate what what Gateway API version the implementation supports. So when we have supported features published in the GatewayClass Status, users will also be able to understand that those are the supported features for a specific Gateway API version.
   185  
   186  This work is likely to require its own small GEP but ideally what this field would mean is that an implementation supports Max(vX.X). 
   187  
   188  The value of it is to provide a better user experience and also more foundation for tools to be able to warn for example when a GatewayClass and CRDs have mismatched versions.