Gateway API introduction — the next-generation Ingress

Gateway API is the next-generation Ingress. It separates the concerns of the infrastructure provider, the cluster operator, and the application developer. This lesson walks the Gateway API, the ownership separation, and the operational discipline.

What Gateway API is

Gateway API is a Kubernetes API for routing traffic into a cluster. It is the successor to Ingress; the design is informed by the operational experience of Ingress.

flowchart LR
    A[Gateway API] --> B[GatewayClass]
    A --> C[Gateway]
    A --> D[HTTPRoute]
    A --> E[TCPRoute]
    A --> F[UDPRoute]
    A --> G[TLSRoute]
    A --> H[GRPCRoute]

The Gateway API has multiple resources. Each resource has a specific role.

The ownership separation

The Gateway API separates the concerns of three roles:

flowchart LR
    A[Infrastructure provider] --> B[GatewayClass]
    A --> C[Gateway]
    D[Cluster operator] --> C
    D --> E[ReferenceGrant]
    F[Application developer] --> G[HTTPRoute]
    G --> C

The roles:

• Infrastructure provider: defines the GatewayClass and the Gateways. Owns the load balancer.
• Cluster operator: manages the Gateways and the ReferenceGrants. Owns the routing.
• Application developer: creates the HTTPRoute that references the Gateway. Owns the application routing.

The ownership separation is the basis of multi-tenancy in the cluster.

The GatewayClass

The GatewayClass is the 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 GatewayClass is created by the infrastructure provider. The cluster operator and the application developer reference the GatewayClass.

The Gateway

The Gateway is the resource that defines the load balancer instance:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: prod-app
spec:
  gatewayClassName: nginx
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: prod-tls
      allowedRoutes:
        namespaces:
          from: Same

The Gateway is created by the cluster operator. The Gateway defines the listeners, the TLS, and the allowed routes.

The HTTPRoute

The HTTPRoute is the resource that defines the HTTP routing:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: billing
  namespace: prod-app
spec:
  parentRefs:
    - name: prod-gateway
  hostnames:
    - billing.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: billing
          port: 80

The HTTPRoute is created by the application developer. The HTTPRoute references the Gateway and defines the routing rules.

The comparison to Ingress

The Gateway API compared to Ingress:

The Gateway API is the future of the Kubernetes HTTP gateway. The cluster operator should plan the migration.

The failure modes

The Gateway API’s failure modes:

• GatewayClass missing: the GatewayClass is not installed. The Gateway is not served. The fix is to install the GatewayClass.
• Gateway not ready: the Gateway’s listener is not configured. The fix is to verify the Gateway.
• HTTPRoute not bound: the HTTPRoute is not bound to the Gateway. The fix is to verify the parentRefs.
• ReferenceGrant missing: the cross-namespace reference is denied. The fix is to add the ReferenceGrant.
• TLS error: the TLS certificate is invalid. The fix is to update the certificate.

The operational discipline

The Gateway API’s operational discipline:

• Document the Gateway API design. The design is the cluster’s HTTP gateway configuration.
• Audit the Gateway API at every change. The Gateway API is critical configuration.
• Test the Gateway API in staging. The Gateway API must work for the workload.
• Plan the Gateway API’s evolution. The Gateway API is the future of the Kubernetes HTTP gateway.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The Gateway API is the next-generation Ingress. The cluster operator must plan the migration.
• Document the Gateway API design. The design is the cluster’s HTTP gateway configuration.
• Audit the Gateway API at every change. The Gateway API is critical configuration.
• Test the Gateway API in staging. The Gateway API must work for the workload.
• Plan the Gateway API’s evolution. The Gateway API is the future of the Kubernetes HTTP gateway.
• 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.