このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Using Gateway API
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 routes.
Gateway API and Kong’s implementation of Gateway API are both in alpha stage and under active development. Features and implementation specifics will change before their initial general availability release.
Supported Gateway API Resources
Currently, the Kong Ingress Controller’s implementation of the Gateway API supports the following resources:
Enable the feature
The Gateway API CRDs are not yet available by default in Kubernetes. You must first install them.
The default controller configuration enables Gateway API handling, however the
alpha features of Gateway API are still behind a feature flag in Kong Ingress Controller.
To enable it, set ingressController.env.feature_gates: GatewayAlpha=true
in your Helm
values.yaml
, or set CONTROLLER_FEATURE_GATES=GatewayAlpha=true
if not using Helm.
Note that you must restart Pods with this flag set after installing the Gateway API CRDs.
If using Helm, you must use chart version 2.7 or higher. Older versions do not include the ServiceAccount permissions necessary for KIC to read Gateway API resources.
Testing connectivity to Kong
This guide assumes that the PROXY_IP
environment variable is
set to contain the IP address or URL pointing to Kong.
Follow one of the
deployment guides to configure this environment variable.
If everything is set up correctly, making a request to Kong should return HTTP 404 Not Found.
Note: If you are running the example using Minikube on MacOS, you may need to run
minikube tunnel
in a separate terminal window. This exposes LoadBalancer services externally, which is not enabled by default.
$ curl -i $PROXY_IP
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Content-Length: 48
Server: kong/1.2.1
{"message":"no Route matched with those values"}
This is expected, as Kong does not yet know how to proxy the request.
Set up an echo service
Set up an echo service to demonstrate how to use the Kong Ingress Controller:
kubectl apply -f https://docs.jp.konghq.com/assets/kubernetes-ingress-controller/examples/echo-service.yaml
Add a GatewayClass and Gateway
The Gateway resource represents the proxy instance that handles traffic for a set of Gateway API routes, and a GatewayClass describes characteristics shared by all Gateways of a given type.
Add a GatewayClass:
$ echo "apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
name: kong
annotations:
konghq.com/gatewayclass-unmanaged: 'true'
spec:
controllerName: konghq.com/kic-gateway-controller
" | kubectl apply -f -
gatewayclass.gateway.networking.k8s.io/kong created
Add a Gateway:
$ echo "apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
name: kong
spec:
gatewayClassName: kong
listeners:
- name: proxy
port: 80
hostname: kong.example
protocol: HTTP
" | kubectl apply -f -
gateway.gateway.networking.k8s.io/kong created
This configuration does create an HTTPS listen, as this requires a certificate. If you have a TLS Secret you wish to use, you can add an HTTPS listen with:
kubectl patch --type=json gateway kong -p='[{
"op":"add",
"path":"/spec/listeners/-",
"value":{
"name":"proxy-ssl",
"hostname":"kong.example",
"port":443,
"protocol":"HTTPS",
"tls":{
"certificateRefs":[{
"group":"",
"kind":"Secret",
"name":"example-cert-secret"
}]
}
}
}]'
Change example-cert-secret
to the name of your Secret.
To configure KIC to reconcile the Gateway resource, you must set the
konghq.com/gatewayclass-unmanaged
annotation as the example in GatewayClass resource used in
spec.gatewayClassName
in Gateway resource. Also, the
spec.controllerName
of GatewayClass needs to be same as the value of the
--gateway-api-controller-name
flag configured in KIC. For more information, see kic-flags.
You can check to confirm if KIC has updated the bound Gateway by inspecting the list of associated addresses:
kubectl get gateway kong -o=jsonpath='{.status.addresses}' | jq
[
{
"type": "IPAddress",
"value": "10.96.179.122"
},
{
"type": "IPAddress",
"value": "172.18.0.240"
}
]
Add an HTTPRoute
HTTPRoute resources are similar to Ingress resources: they contain a set of matching criteria for HTTP requests and upstream Services to route those requests to.
The Gateway API specification binds HTTPRoutes to one or more listeners in a Gateway resource. These listeners have a specific port, and HTTPRoutes should only be available on their listeners’ ports per the specification. Kong’s HTTP proxy implementation doesn’t support this. If you configure multiple HTTP ports, Kong serves all HTTP routes on all ports.
$ echo "apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
name: echo
annotations:
konghq.com/strip-path: 'true'
spec:
parentRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: kong
hostnames:
- kong.example
rules:
- backendRefs:
- group: ""
kind: Service
name: echo
port: 80
weight: 1
matches:
- path:
type: PathPrefix
value: /echo
" | kubectl apply -f -
After creating an HTTPRoute, accessing /echo/hostname
forwards a request to the
echo service’s /hostname
path, which yields the name of the pod that served the request:
curl -i http://kong.example/echo/hostname --resolve kong.example:80:$PROXY_IP
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 21
Connection: keep-alive
Date: Fri, 28 Oct 2022 08:18:18 GMT
X-Kong-Upstream-Latency: 1
X-Kong-Proxy-Latency: 0
Via: kong/3.1.1
echo-658c5ff5ff-8cvgj%
Traffic splitting with HTTPRoute
HTTPRoute contains a BackendRefs
field, which allows
users to specify weight
parameters for echo BackendRef
.
This can be used to perform traffic splitting.
To do so, you can deploy a second echo Service so that you have
a second BackendRef
to use for traffic splitting.
kubectl apply -f https://docs.jp.konghq.com/assets/kubernetes-ingress-controller/examples/echo-services.yaml
Note: This example contains the previous echo Service so you may deploy it without deploying the previous example from the Set up an echo service section.
Now that those two Services are deployed, you can now deploy your HTTPRoute. This will perform the traffic splitting between them using the weight parameters:
echo 'apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
name: echo
annotations:
konghq.com/strip-path: "true"
spec:
parentRefs:
- name: kong
rules:
- matches:
- path:
type: PathPrefix
value: /echo
backendRefs:
- name: echo
kind: Service
port: 80
weight: 75
- name: echo2
kind: Service
port: 80
weight: 25
' | kubectl apply -f -
Now, accessing /echo/hostname
should distribute around 75% of requests to Service
echo and around 25% of requests to Service echo2.
curl http://kong.example/echo/hostname --resolve kong.example:80:$PROXY_IP
echo2-7cb798f47-gh4xg%
curl http://kong.example/echo/hostname --resolve kong.example:80:$PROXY_IP
echo-658c5ff5ff-8cvgj%
curl http://kong.example/echo/hostname --resolve kong.example:80:$PROXY_IP
echo-658c5ff5ff-8cvgj%
curl http://kong.example/echo/hostname --resolve kong.example:80:$PROXY_IP
echo-658c5ff5ff-8cvgj%
Beta limitations
Kong Ingress Controller Gateway API support is a work in progress, and not all features of Gateway APIs are supported. In particular:
-
queryParam
matches are not supported. - Gateways are not provisioned automatically.
- Kong only supports a single Gateway per GatewayClass.
- HTTPRoutes cannot be bound to a specific port using a ParentReference. Kong serves all HTTP routes on all HTTP listeners.