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

     1  # GatewayClass
     2  
     3  ??? success "Standard Channel in v0.5.0+"
     4  
     5      The `GatewayClass` resource is Beta and part of the Standard Channel in `v0.5.0+`.
     6  
     7  [GatewayClass][gatewayclass] is cluster-scoped resource defined by the
     8  infrastructure provider. This resource represents a class of Gateways that can
     9  be instantiated.
    10  
    11  > Note: GatewayClass serves the same function as the
    12  > [`networking.IngressClass` resource][ingress-class-api].
    13  
    14  ```yaml
    15  kind: GatewayClass
    16  metadata:
    17    name: cluster-gateway
    18  spec:
    19    controllerName: "example.net/gateway-controller"
    20  ```
    21  
    22  We expect that one or more `GatewayClasses` will be created by the
    23  infrastructure provider for the user. It allows decoupling of which mechanism
    24  (e.g. controller) implements the `Gateways` from the user. For instance, an
    25  infrastructure provider may create two `GatewayClasses` named `internet` and
    26  `private` to reflect `Gateways` that define Internet-facing vs private, internal
    27  applications.
    28  
    29  ```yaml
    30  kind: GatewayClass
    31  metadata:
    32    name: internet
    33    ...
    34  ---
    35  kind: GatewayClass
    36  metadata:
    37    name: private
    38    ...
    39  ```
    40  
    41  The user of the classes will not need to know *how* `internet` and `private` are
    42  implemented. Instead, the user will only need to understand the resulting
    43  properties of the class that the `Gateway` was created with.
    44  
    45  ### GatewayClass parameters
    46  
    47  Providers of the `Gateway` API may need to pass parameters to their controller
    48  as part of the class definition. This is done using the
    49  `GatewayClass.spec.parametersRef` field:
    50  
    51  ```yaml
    52  # GatewayClass for Gateways that define Internet-facing applications.
    53  kind: GatewayClass
    54  metadata:
    55    name: internet
    56  spec:
    57    controllerName: "example.net/gateway-controller"
    58    parametersRef:
    59      group: example.net/v1alpha1
    60      kind: Config
    61      name: internet-gateway-config
    62  ---
    63  apiVersion: example.net/v1alpha1
    64  kind: Config
    65  metadata:
    66    name: internet-gateway-config
    67  spec:
    68    ip-address-pool: internet-vips
    69    ...
    70  ```
    71  
    72  Using a Custom Resource for `GatewayClass.spec.parametersRef` is encouraged
    73  but implementations may resort to using a ConfigMap if needed.
    74  
    75  ### GatewayClass status
    76  
    77  `GatewayClasses` MUST be validated by the provider to ensure that the configured
    78  parameters are valid. The validity of the class will be signaled to the user via
    79  `GatewayClass.status`:
    80  
    81  ```yaml
    82  kind: GatewayClass
    83  ...
    84  status:
    85    conditions:
    86    - type: Accepted
    87      status: False
    88      ...
    89  ```
    90  
    91  A new `GatewayClass` will start with the `Accepted` condition set to
    92  `False`. At this point the controller has not seen the configuration. Once the
    93  controller has processed the configuration, the condition will be set to
    94  `True`:
    95  
    96  ```yaml
    97  kind: GatewayClass
    98  ...
    99  status:
   100    conditions:
   101    - type: Accepted
   102      status: True
   103      ...
   104  ```
   105  
   106  If there is an error in the `GatewayClass.spec`, the conditions will be
   107  non-empty and contain information about the error.
   108  
   109  ```yaml
   110  kind: GatewayClass
   111  ...
   112  status:
   113    conditions:
   114    - type: Accepted
   115      status: False
   116      Reason: BadFooBar
   117      Message: "foobar" is an FooBar.
   118  ```
   119  
   120  ### GatewayClass controller selection
   121  
   122  The `GatewayClass.spec.controller` field determines the controller implementation
   123  responsible for managing the `GatewayClass`. The format of the field is opaque
   124  and specific to a particular controller. The GatewayClass selected by a given
   125  controller field depends on how various controller(s) in the cluster interpret
   126  this field.
   127  
   128  It is RECOMMENDED that controller authors/deployments make their selection
   129  unique by using a domain / path combination under their administrative control
   130  (e.g. controller managing of all `controller`s starting with `example.net` is the
   131  owner of the `example.net` domain) to avoid conflicts.
   132  
   133  Controller versioning can be done by encoding the version of a controller into
   134  the path portion. An example scheme could be (similar to container URIs):
   135  
   136  ```text
   137  example.net/gateway/v1   // Use version 1
   138  example.net/gateway/v2.1 // Use version 2.1
   139  example.net/gateway      // Use the default version
   140  ```
   141  
   142  [gatewayclass]: /reference/spec/#gateway.networking.k8s.io/v1beta1.GatewayClass
   143  [ingress-class-api]: https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class