You are browsing documentation for an outdated version. See the
latest documentation here.
Gateway API is a set of resources for
configuring networking in Kubernetes. It expands on Ingress to configure
additional types of routes (TCP, UDP, and TLS in addition to HTTP/HTTPS),
support backends other than Service, and manage the proxies that implement
Gateway API and Kong’s implementation of Gateway API are both under active
development. Features and implementation specifics will change before their
initial general availability release.
A Gateway resource
describes an application or cluster feature that can handle Gateway API routing
rules, directing inbound traffic to Services following the rules provided. For
Kong’s implementation, a Gateway corresponds to a Kong Deployment managed by
the ingress controller.
Typically, Gateway API implementations manage the resources associated with a
Gateway on behalf of users: creating a Gateway resource will trigger automatic
provisioning of Deployments/Services/etc. with configuration matching the
Gateway’s listeners and addresses. The Kong alpha implementation does not
automatically manage Gateway provisioning: you must create the Kong and ingress
controller Deployment and proxy Service yourself following the Gateway installation guide.
Because the Kong Deployment and its configuration are not managed
automatically, listener and address configuration are not set for you. You must
configure your Deployment and Service to match your Gateway’s configuration.
For example, with this Gateway:
- name: proxy
- name: proxy-ssl
- name: proxy-tcp-9901
- name: proxy-udp-9902
- name: proxy-tls-9903
requires a proxy Service that includes all the requested listener ports:
- port: 80
- port: 443
- port: 9901
- port: 9902
- port: 9903
and matching Kong
proxy_listen configuration in the container environment:
KONG_PROXY_LISTEN="0.0.0.0:8000 reuseport backlog=16384, 0.0.0.0:8443 http2 ssl reuseport backlog=16384 http2"
KONG_STREAM_LISTEN="0.0.0.0:9901 reuseport backlog=16384, 0.0.0.0:9902 reuseport backlog=16384 udp", 0.0.0.0:9903 reuseport backlog=16384 ssl"
The Helm chart manages
both of these from the
proxy configuration block:
- containerPort: 9901
- containerPort: 9902
- containerPort: 9903
Ports missing appropriate Kong-side configuration will result in an error
condition in the Gateway’s status:
message: no Kong listen with the requested protocol is configured for the
Listener compatibility and handling multiple Gateways
During the alpha, without automatic Gateway Deployment provisioning, Kong’s
implementation can only handle a single GatewayClass, and only one Gateway in
that GatewayClass. Although the controller will attempt to handle configuration
from all Gateways in its GatewayClass, adding more than one Gateway is not yet
supported and will likely result in unexpected behavior. If you wish to use
multiple Gateways, define multiple GatewayClasses and install a separate
Deployment for each.
For background, Gateway API allows implementations to collapse compatible
listens and Gateways:
An implementation MAY group Listeners by Port and then collapse each group of
Listeners into a single Listener if the implementation determines that the
Listeners in the group are “compatible”. An implementation MAY also group
together and collapse compatible Listeners belonging to different Gateways.
Compatibility means that listeners can coexist: for example, two HTTP listens
can coexist on the same port because Gateways can still route inbound requests
using the HTTP
Host header, whereas two TCP listens cannot coexist on the
same port because the port is the only characteristic that can select between
If there is a conflict between listeners on a Gateway, the controller will mark
the conflict in the Gateway status and not add routes that require the
conflicting listener. The controller cannot, however, perform these same
validity checks across separate Gateway resources.