GatewayClass — the infrastructure provider resource

GatewayClass is the resource that defines the underlying load balancer. The infrastructure provider creates the GatewayClass. This lesson walks the GatewayClass, the controller reference, and the operational discipline.

The GatewayClass

The GatewayClass is the cluster-wide resource that defines the underlying load balancer:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx
spec:
  controllerName: gateway.nginx.org/nginx

The controllerName field identifies the controller that implements the GatewayClass. The infrastructure provider creates the GatewayClass and installs the controller.

sequenceDiagram
    autonumber
    participant IP as Infrastructure
    participant GC as GatewayClass
    participant C as Controller
    participant G as Gateway
    IP->>GC: create GatewayClass
    IP->>C: install controller
    C->>GC: watch GatewayClass
    G->>GC: reference GatewayClass
    C->>G: implement Gateway

The controller watches the GatewayClass and implements the Gateways that reference the GatewayClass.

The parametersReference

The GatewayClass can reference additional configuration:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx
spec:
  controllerName: gateway.nginx.org/nginx
  parametersRef:
    group: example.com
    kind: NginxGatewayClassConfig
    name: nginx-config
    namespace: gateway-system

The parametersRef field references a custom resource that holds the controller-specific configuration. The configuration is controller-specific.

The conformance level

The GatewayClass has a conformance level:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx
  annotations:
    conformance.sigs.k8s.io/gateway-level: extended
spec:
  controllerName: gateway.nginx.org/nginx

The conformance levels are:

• Core: the controller passes the core test suite.
• Extended: the controller passes the extended test suite (including TLS, multiple listeners, etc.).
• Implementation-specific: the controller has implementation-specific features.

The conformance level is published by the SIG-Network.

The failure modes

The GatewayClass’s failure modes:

• GatewayClass missing: the GatewayClass is not installed. The Gateway is not served. The fix is to install the GatewayClass.
• Controller missing: the GatewayClass’s controller is not installed. The Gateway is not served. The fix is to install the controller.
• parametersRef invalid: the parametersRef is invalid. The fix is to verify the parametersRef.
• Conformance level unknown: the controller’s conformance level is unknown. The fix is to verify the controller’s documentation.

The operational discipline

The GatewayClass’s operational discipline:

• Document the GatewayClass. The GatewayClass is the cluster’s HTTP gateway configuration.
• Audit the GatewayClass at every change. The GatewayClass is critical configuration.
• Test the GatewayClass in staging. The GatewayClass must work for the workload.
• Plan the GatewayClass’s evolution. The GatewayClass can be replaced with a new controller.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The GatewayClass is the cluster-wide controller reference. The infrastructure provider creates the GatewayClass.
• Document the GatewayClass. The GatewayClass is the cluster’s HTTP gateway configuration.
• Audit the GatewayClass at every change. The GatewayClass is critical configuration.
• Test the GatewayClass in staging. The GatewayClass must work for the workload.
• Plan the GatewayClass’s evolution. The GatewayClass can be replaced with a new controller.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Train the teams on the roles. The teams must understand the ownership separation.
• Document the migration path. The migration is a significant change.