Custom resources
Learn how the kgateway and Kubernetes Gateway API custom resources interact.
Custom resource overview
The following image illustrates how the kgateway custom resources interact with the Kubernetes Gateway API custom resources to provide advanced routing, traffic management, security, resiliency, and integration capabilities. To learn more about each custom resource, see Kubernetes Gateway API resources and kgateway resources.
Kubernetes Gateway API resources
Review the Kubernetes Gateway API resources that you use to set up gateway proxies and configure routing for your apps.
For more information, see the Kubernetes Gateway API introduction.
Gateway and GatewayClass
The Gateway custom resource is a network abstraction that defines a point of access at which traffic can be forwarded to a backend in a Kubernetes cluster. A Gateway defines the listeners that you want to open, including the ports, protocols, and hostnames that you want to listen on for incoming traffic. You can also specify how incoming, encrypted traffic is handled. For example, encrypted traffic can be terminated at the gateway or passed through to a backend in the cluster.
To spin up a Gateway and manage its lifecycle, a gateway controller is used. The gateway controller is defined in the GatewayClass resource and manages the underlying infrastructure to ensure that traffic to endpoints is routed accordingly. When you install kgateway, a GatewayClass resource is automatically created that points to the kgateway controller. For more information, see GatewayClass.
HTTPRoute and TCPRoute
To configure routing, the Kubernetes Gateway API provides several routing resources, such as an HTTPRoute and TCPRoute. These routes attach to a Gateway resource and define how incoming traffic is matched and forwarded to a backing destination.
- HTTPRoute: The most commonly used route resource, that configures traffic routing for HTTP and HTTPS traffic.
- TCPRoute: A resource to route TCP requests.
While the Kubernetes Gateway API provides the functionality for basic request matching, redirects, rewrites, and header manipulation, it is missing more complex traffic management, resiliency, and security features, such as transformations, access logging, or route delegation.
You can extend the Kubernetes Gateway API features by leveraging the kgateway policy custom resources. Policies allow you to apply intelligent traffic management, resiliency, and security standards to an HTTPRoute or Gateway.
Kubernetes Services
Kubernetes Services expose Kubernetes pods within and outside a Kubernetes cluster so that other network endpoints can communicate with them. In the context of the Kubernetes Gateway API, the Kubernetes Service represents an app within the cluster that you want to route traffic to from outside the cluster. The Service is referenced in the HTTPRoute resource, including the port that you want to send traffic to.
If traffic matches the conditions that are defined in the HTTPRoute, the Gateway forwards traffic to the Kubernetes Service that is referenced in the HTTPRoute.
ReferenceGrant
A ReferenceGrant allows a Kubernetes Gateway API resource, such as an HTTPRoute, to reference resources that exist in other namespaces. For example, if you create an HTTPRoute resource in namespace1, but the Kubernetes Service or Backend that you want to route to is in namespace2, you must create a ReferenceGrant to allow communication between these resources.
Kgateway resources
Review the kgateway resources that you use to bootstrap, configure, and customize your gateway proxy, and the policies that you can leverage to add additional traffic management, resiliency, and security capabilities to your gateway and routes.
GatewayParameters
When you create a Gateway resource, a default gateway proxy template is used to automatically spin up and bootstrap a gateway proxy deployment and service in your cluster. The template includes Envoy configuration that binds the gateway proxy deployment to the Gateway resource that you created. In addition, the settings in the GatewayParameters resource are used to configure the gateway proxy.
To learn more about the default gateway setup and how these resource interact with each other, see Default gateway proxy setup.
Policies
While the Kubernetes Gateway API allows you to do simple routing, such as to match, redirect, or rewrite requests, you might want additional capabilities in your API gateway, such as access logging or transformations. Policies allow you to apply intelligent traffic management, resiliency, and security standards to HTTPRoutes or Gateways.
Kgateway uses the following custom resources to attach policies to routes and gateway listeners:
- DirectResponse: Directly respond to incoming requests with a custom HTTP response code and body.
- HTTPListenerPolicy: Apply policies to all HTTP and HTTPS listeners.
- TrafficPolicy: Attach policies to routes in an HTTPRoute resource.
Backends
For workloads within your cluster, you can can route incoming traffic to their Kubernetes Service. But what if you have external services such as static hostnames or AWS Lambda functions that you want to route traffic to?
You can use a kgateway Backend resource to accomplish this task. Similar to using Kubernetes Services, you reference the Backend in your HTTPRoute resource. For more information about Backends, see Backends.