Default 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, the following 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 agentgateway GatewayClass is for when you want to use an agentgateway proxy in kgateway.
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: agentgateway
spec:
controllerName: kgateway.dev/agentgateway
description: Specialized class for agentgateway.The kgateway.dev/kgateway controller watches the resources in your cluster. When a Gateway resource is created that references the kgateway or kgateway-waypoint 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.
Similarily, the kgateway.dev/agentgateway controller watches for Gateways with the agentgateway GatewayClass. The controller spins up an agentgateway proxy with the default agentgateway proxy template. The controller also translates other resources, such as HTTPRoute, TrafficPolicy, HTTPListenerPolicy, and more, into valid agentgateway 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 for Envoy and agentgateway proxies 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.
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 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 Helm chart. You can change the default configuration for your gateway proxies by creating a custom GatewayParameters resource. You then use this GatewayParameters resource to spin up different types of gateway proxies.
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 gateway proxy configuration. To add them, you can create a separate GatewayParameters resource where you add these annotations. For more customization options, see Customize the gateway.
Reserved ports
The following ports are reserved by Kgateway and cannot be used when configuring your gateway proxy.
| Port | Description |
|---|---|
| 19000 | The Envoy admin port. Gateway proxies expose an admin interface on this port that you can use to access important proxy information, such as the config dump, heap dump, healthchecks, and memory allocation. |
| 15000 | The agentgateway admin port. Agentgateway proxies expose several endpoints on this port that you can use to access important proxy information, such as the config dump (15000/config_dump) and a read-only user interface (15000/ui). |
| 8082 | The readiness port. This port can be used to determine if the gateway proxy is ready to receive traffic. |
| 9091 | The Prometheus scraping port. Gateway proxies expose all metrics on this port so that Prometheus can scrape them. |
Note that if you configure one of these ports, the gateway proxy still deploys. However, you see error messages, such as the following in the logs.
err="failed to apply object apps/v1, Kind=Deployment example-gateway: failed to create typed patch object
(gwtest/example-gateway; apps/v1, Kind=Deployment): .spec.template.spec.containers[name=\"kgateway-proxy\"].
ports: duplicate entries for key [containerPort=9091,protocol=\"TCP\"]"