Documentation
Gateway setup
Default gateway proxy setup

Default gateway proxy setup

Learn about the different kgateway and Kubernetes resources that make up your gateway proxy deployment.

GatewayClass

The GatewayClass is a Kubernetes Gateway API-native resource that defines the controller that spins up and configures gateway proxies in your environment.

When you install kgateway, two default GatewayClass resources are automatically created with the following configuration.

The kgateway GatewayClass is the standard class that you use for most Gateways.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: kgateway
spec:
  controllerName: kgateway.dev/kgateway
  description: Standard class for managing Gateway API ingress traffic.

The kgateway-waypoint GatewayClass is for when you use kgateway as a waypoint in an Istio Ambient service mesh setup.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: kgateway-waypoint
spec:
  controllerName: kgateway.dev/kgateway
  description: Specialized class for Istio ambient mesh waypoint proxies.

The kgateway.dev/kgateway controller implements the Kubernetes Gateway API and provides an abstraction of the gateway’s underlying infrastructure. The controller watches the resources in your cluster. When a Gateway resource is created that references this GatewayClass, the controller spins up an Envoy-based gateway proxy by using the configuration that is defined in the GatewayParameters resource. The controller also translates other resources, such as HTTPRoute, TrafficPolicy, HTTPListenerPolicy, and more, into valid Envoy configuration, and applies the configuration to the gateway proxies it manages.

Gateway proxy template

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.

The resulting gateway proxy is managed for you and its configuration is automatically updated based on the settings in the GatewayParameters resource. To publicly expose the gateway proxy deployment, a service of type LoadBalancer is created for you. Depending on the cloud provider that you use, the LoadBalancer service is assigned a public IP address or hostname that you can use to reach the gateway. To expose an app on the gateway, you must create an HTTPRoute resource and define the matchers and filter rules that you want to apply before forwarding the request to the app in your cluster. You can review the Get started, traffic management, security, and resiliency guides to find examples for how to route and secure traffic to an app.

You can change the default configuration of your gateway proxy by creating custom GatewayParameters resources, or updating the default GatewayParameters values in your kgateway Helm chart. If you change the values in the Helm chart, kgateway automatically applies the changes to the default GatewayParameters resources.

ℹ️
Do not edit or change the default GatewayParameters resource directly. Always update the values in the kgateway Helm chart so that they persist between upgrades.

If you do not want to use the default gateway proxy template to bootstrap your proxies, you can choose to create a self-managed gateway. With self-managed gateways, you are responsible for defining the proxy deployment template that you want to bootstrap your proxies with. For more information, see Self-managed gateways (BYO).

GatewayParameters

GatewayParameters is a kgateway custom resource that specifies the configuration for the gateway proxies in your cluster.

To spin up new gateway proxies, the kgateway controller uses a gateway proxy template and the configuration in the default GatewayParameters resource. You can change the default configuration for your gateway proxies by updating the respective values in the kgateway Helm chart. You can also create additional GatewayParameters resources to spin up different types of gateway proxies.

ℹ️
Do not edit or change the default GatewayParameters resource directly. Always update the values in the kgateway Helm chart so that they persist between upgrades, or create your own GatewayParameters resource that holds your custom values. Note that you are responsible to maintain any GatewayParameters resources that you manually created.

For example, you might want to pair your gateway with a Network Load Balancer (NLB) instance in AWS. To properly pair and configure the gateway with an NLB, specific annotations on the gateway proxy are required. These annotations are not included in the default GatewayParameters resource. To add them, you can create a separate GatewayParameters resource where you add these annotations. For more customization options, see Customize the gateway.

Gateway customization