sigs.k8s.io/gateway-api@v1.0.0/site-src/concepts/guidelines.md (about)

     1  # Design guidelines
     2  
     3  There are some general design guidelines used throughout this API.
     4  
     5  !!! note
     6      Throughout the Gateway API documentation and specification,
     7      keywords such as "MUST", "MAY", and "SHOULD" are used
     8      broadly. These should be interpreted as described in RFC 2119.
     9  
    10  ## Single resource consistency
    11  
    12  The Kubernetes API guarantees consistency only on a single resource level. There
    13  are a couple of consequences for complex resource graphs as opposed to single
    14  resources:
    15  
    16  *   Error checking of properties spanning multiple resource will be asynchronous
    17      and eventually consistent. Simple syntax checks will be possible at the
    18      single resource level, but cross resource dependencies will need to be
    19      handled by the controller.
    20  *   Controllers will need to handle broken links between resources and/or
    21      mismatched configuration.
    22  
    23  ## Conflicts
    24  
    25  Separation and delegation of responsibility among independent actors (e.g
    26  between cluster ops and application developers) can result in conflicts in the
    27  configuration. For example, two application teams may inadvertently submit
    28  configuration for the same HTTP path.
    29  
    30  In most cases, guidance for conflict resolution is provided along with the
    31  documentation for fields that may have a conflict. If a conflict does not have a
    32  prescribed resolution, the following guiding principles should be applied:
    33  
    34  * Prefer not to break things that are working.
    35  * Drop as little traffic as possible.
    36  * Provide a consistent experience when conflicts occur.
    37  * Make it clear which path has been chosen when a conflict has been identified.
    38    Where possible, this should be communicated by setting appropriate status
    39    conditions on relevant resources.
    40  * More specific matches should be given precedence over less specific ones.
    41  * The resource with the oldest creation timestamp wins.
    42  * If everything else is equivalent (including creation timestamp), precedences
    43    should be given to the resource appearing first in alphabetical order
    44    (namespace/name). For example, foo/bar would be given precedence over foo/baz.
    45  
    46  ## Gracefully Handling Future API Versions
    47  
    48  An important consideration when implementing this API is how it might change in
    49  the future. Similar to the Ingress API before it, this API is designed to be
    50  implemented by a variety of different products within the same cluster. That
    51  means that the API version your implementation was developed with may be
    52  different than the API version it is used with.
    53  
    54  At a minimum, the following requirements must be met to ensure future versions
    55  of the API do not break your implementation:
    56  
    57  * Handle fields with loosened validation without crashing
    58  * Handle fields that have transitioned from required to optional without
    59    crashing
    60  
    61  ### Supported API Versions
    62  
    63  The version of Gateway API CRDs that is installed in a cluster can be determined
    64  by looking at the `gateway.networking.k8s.io/bundle-version` annotation on each
    65  CRD. Each implementation MUST compare that with the list of versions that it
    66  recognizes and supports. Implementations with a GatewayClass MUST publish the
    67  `SupportedVersion` condition on the GatewayClass to indicate whether the CRDs
    68  installed in the cluster are supported.
    69  
    70  ## Limitations of CRD and Webhook Validation
    71  
    72  CRD and webhook validation is not the final validation i.e. webhook is "nice UX"
    73  but not schema enforcement. This validation is intended to provide immediate
    74  feedback to users when they provide an invalid configuration. Write code
    75  defensively with the assumption that at least some invalid input (Gateway API
    76  resources) will reach your controller. Both Webhook and CRD validation is not
    77  fully reliable because it:
    78  
    79  * May not be deployed correctly.
    80  * May be loosened in future API releases. (Fields may contain values with less
    81    restrictive validation in newer versions of the API).
    82  
    83  *Note: These limitations are not unique to Gateway API and apply more broadly to
    84  any Kubernetes CRDs and webhooks.*
    85  
    86  Implementers should ensure that, even if unexpected values are encountered in
    87  the API, their implementations are still as secure as possible and handle this
    88  input gracefully. The most common response would be to reject the configuration
    89  as malformed and signal the user via a condition in the status block. To avoid
    90  duplicating work, Gateway API maintainers are considering adding a shared
    91  validation package that implementations can use for this purpose. This is
    92  tracked by [#926](https://github.com/kubernetes-sigs/gateway-api/issues/926).
    93  
    94  ### Expectations
    95  
    96  We expect there will be varying levels of conformance among the
    97  different providers in the early days of this API. Users can use the
    98  results of the conformance tests to understand areas where there may
    99  be differences in behavior from the spec.
   100  
   101  ### Implementation-specific
   102  
   103  In some aspects of the API, we give the user an ability to specify usage of the
   104  feature, however, the exact behavior may depend on the underlying
   105  implementation. For example, regular expression matching is present in all
   106  implementations but specifying an exact behavior is impossible due to
   107  subtle differences between the underlying libraries used (e.g. PCRE, ECMA,
   108  Re2). It is still useful for our users to spec out the feature as much as
   109  possible, but we acknowledge that the behavior for some subset of the API may
   110  still vary (and that's ok).
   111  
   112  These cases will be specified as defining delimited parts of the API
   113  "implementation-specific".
   114  
   115  
   116  ## Kind vs. Resource
   117  
   118  Similar to other Kubernetes APIs, Gateway API uses "Kind" instead of "Resource"
   119  in object references throughout the API. This pattern should be familiar to
   120  most Kubernetes users.
   121  
   122  Per the [Kubernetes API conventions][1], this means that all implementations of
   123  this API should have a predefined mapping between kinds and resources. Relying
   124  on dynamic resource mapping is not safe.
   125  
   126  ## API Conventions
   127  
   128  Gateway API follows Kubernetes API [conventions][1]. These conventions
   129  are intended to ease client development and ensure that configuration
   130  mechanisms can consistently be implemented across a diverse set of use
   131  cases. In addition to the Kubernetes API conventions, Gateway API has the
   132  following conventions:
   133  
   134  ### List Names
   135  
   136  Another convention this project uses is for plural field names for lists
   137  in our CRDs. We use the following rules:
   138  
   139  - If the field name is a noun, use a plural value.
   140  - If the field name is a verb, use a singular value.
   141  
   142  [1]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md