GatewayClass

Standard Channel since v0.5.0

The GatewayClass resource is GA and has been part of the Standard Channel since v0.5.0. For more information on release channels, refer to our versioning guide.

GatewayClass is cluster-scoped resource defined by the infrastructure provider. This resource represents a class of Gateways that can be instantiated.

Note: GatewayClass serves the same function as the networking.IngressClass resource.

  1. kind: GatewayClass
  2. metadata:
  3.   name: cluster-gateway
  4. spec:
  5.   controllerName: "example.net/gateway-controller"

We expect that one or more GatewayClasses will be created by the infrastructure provider for the user. It allows decoupling of which mechanism (e.g. controller) implements the Gateways from the user. For instance, an infrastructure provider may create two GatewayClasses named internet and private to reflect Gateways that define Internet-facing vs private, internal applications.

  1. kind: GatewayClass
  2. metadata:
  3.   name: internet
  4.   ...
  5. ---
  6. kind: GatewayClass
  7. metadata:
  8.   name: private
  9.   ...

The user of the classes will not need to know how internet and private are implemented. Instead, the user will only need to understand the resulting properties of the class that the Gateway was created with.

GatewayClass parameters

Providers of the Gateway API may need to pass parameters to their controller as part of the class definition. This is done using the GatewayClass.spec.parametersRef field:

  1. # GatewayClass for Gateways that define Internet-facing applications.
  2. kind: GatewayClass
  3. metadata:
  4.   name: internet
  5. spec:
  6.   controllerName: "example.net/gateway-controller"
  7.   parametersRef:
  8.     group: example.net/v1alpha1
  9.     kind: Config
  10.     name: internet-gateway-config
  11. ---
  12. apiVersion: example.net/v1alpha1
  13. kind: Config
  14. metadata:
  15.   name: internet-gateway-config
  16. spec:
  17.   ip-address-pool: internet-vips
  18.   ...

Using a Custom Resource for GatewayClass.spec.parametersRef is encouraged but implementations may resort to using a ConfigMap if needed.

GatewayClass status

GatewayClasses MUST be validated by the provider to ensure that the configured parameters are valid. The validity of the class will be signaled to the user via GatewayClass.status:

  1. kind: GatewayClass
  2. ...
  3. status:
  4.   conditions:
  5.   - type: Accepted
  6.     status: False
  7.     ...

A new GatewayClass will start with the Accepted condition set to False. At this point the controller has not seen the configuration. Once the controller has processed the configuration, the condition will be set to True:

  1. kind: GatewayClass
  2. ...
  3. status:
  4.   conditions:
  5.   - type: Accepted
  6.     status: True
  7.     ...

If there is an error in the GatewayClass.spec, the conditions will be non-empty and contain information about the error.

  1. kind: GatewayClass
  2. ...
  3. status:
  4.   conditions:
  5.   - type: Accepted
  6.     status: False
  7.     Reason: BadFooBar
  8.     Message: "foobar" is an FooBar.

GatewayClass controller selection

The GatewayClass.spec.controller field determines the controller implementation responsible for managing the GatewayClass. The format of the field is opaque and specific to a particular controller. The GatewayClass selected by a given controller field depends on how various controller(s) in the cluster interpret this field.

It is RECOMMENDED that controller authors/deployments make their selection unique by using a domain / path combination under their administrative control (e.g. controller managing of all controllers starting with example.net is the owner of the example.net domain) to avoid conflicts.

Controller versioning can be done by encoding the version of a controller into the path portion. An example scheme could be (similar to container URIs):

  1. example.net/gateway/v1   // Use version 1
  2. example.net/gateway/v2.1 // Use version 2.1
  3. example.net/gateway      // Use the default version