このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Gateway API
Gateway API is a set of resources for configuring networking in Kubernetes. It expands on Ingress to configure additional types of routes such as TCP, UDP, and TLS in addition to HTTP/HTTPS, and to support backends other than Service, and manage the proxies that implement routes.
Gateway API and Kong’s implementation of Gateway API are both Generally Available for all users.
Gateway API resources will only be reconciled when the Gateway API CRDs are installed in your cluster before Kong Ingress Controller is started. See the getting started page for installation instructions.
Gateway management
A Gateway resource describes an application or cluster feature that can handle Gateway API routing rules, directing inbound traffic to Services by 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 for creating a Gateway resource triggers automatic provisioning of Deployments, Services, and others with configuration by matching the Gateway’s listeners and addresses. The Kong’s implementation does not automatically manage Gateway provisioning.
Because the Kong Deployment and its configuration are not managed automatically, listeners 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.
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example
spec:
gatewayClassName: kong
listeners:
- name: proxy
port: 80
protocol: HTTP
- name: proxy-ssl
port: 443
protocol: HTTPS
hostname: kong.example.com
tls:
mode: Terminate
certificateRefs:
- kind: Secret
name: kong-example-com-cert
- name: proxy-tcp-9901
port: 9901
protocol: TCP
- name: proxy-udp-9902
port: 9902
protocol: UDP
- name: proxy-tls-9903
port: 9903
protocol: TLS
It requires a proxy Service that includes all the requested listener ports.
apiVersion: v1
kind: Service
metadata:
name: proxy
spec:
ports:
- port: 80
protocol: TCP
targetPort: 8000
- port: 443
protocol: TCP
targetPort: 8443
- port: 9901
protocol: TCP
targetPort: 9901
- port: 9902
protocol: UDP
targetPort: 9902
- port: 9903
protocol: TCP
targetPort: 9903
It also matches 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"
Both the Service and proxy_listen
configuration are managed via the Helm chart using the proxy
configuration block.
proxy:
http:
enabled: true
servicePort: 80
containerPort: 8000
tls:
enabled: true
servicePort: 443
containerPort: 8443
stream:
- containerPort: 9901
servicePort: 9901
protocol: TCP
- containerPort: 9902
servicePort: 9902
protocol: UDP
- containerPort: 9903
servicePort: 9903
protocol: TCP
parameters:
- "ssl"
Ports missing appropriate Kong-side configuration results in an error condition in the Gateway’s status.
message: no Kong listen with the requested protocol is configured for the
requested port
reason: PortUnavailable
Listener compatibility and handling multiple Gateways
Each Kong Ingress Controller can be provided with a controller name; if no controller name is provided through the --gateway-api-controller-name
field (or CONTROLLER_GATEWAY_API_CONTROLLER_NAME
environment variable) the default konghq.com/kic-gateway-controller
is used. All the GatewayClass
es referencing such a controller in the controllerName
field are reconciled by the Kong Ingress Controller. Similarly, all the Gateway
s referencing a GatewayClass
that specifies a matching controllerName
are reconciled.
Binding Kong Gateway to a Gateway resource
To configure Kong Ingress Controller to reconcile the Gateway resource, you must set the konghq.com/gatewayclass-unmanaged=true
annotation in your GatewayClass resource.
In addition, the spec.controllerName
in your GatewayClass needs to be properly configured, as explained in the section above. For more information, see kic-flags.
Finally, the spec.gatewayClassName
value in your Gateway resource should match the value in metadata.name
from your GatewayClass
.
You can check to confirm if Kong Ingress Controller has updated the Gateway by inspecting the list of associated addresses. If an IP address is shown, the Gateway
is being managed by Kong.
kubectl get gateway kong -o=jsonpath='{.status.addresses}' | jq
[
{
"type": "IPAddress",
"value": "10.96.179.122"
},
{
"type": "IPAddress",
"value": "172.18.0.240"
}
]
Gateway’s “publish” Service
When an unmanaged Gateway is reconciled by KIC, it gets annotated with konghq.com/publish-service
equal to a Service’s
namespaced name configured in --publish-service
(and optionally in --publish-service-udp
) CLI flag. The annotation value is used by the Gateway controller to
determine its Listeners’ statuses.
Once the Gateway’s
konghq.com/publish-service
annotation is assigned, it will no longer be auto-updated by Kong Ingress Controller to match the--publish-service
CLI flag. If, for any reason, any of those change after the annotation is assigned, the Gateway controller will not be able to determine the Gateway’s Listeners’ statuses. Manual intervention will be required to update the annotation to match the CLI flag.
If you’d like to migrate an already annotated Gateway to a KIC installation that uses another --publish-service
(or --publish-service-udp
), you should modify
the Gateway’s annotation to match the CLI flag. Otherwise, you may experience the Gateway controller getting stuck looking up the Service:
One of publish services defined in Gateway's "konghq.com/publish-service" annotation didn't match controller manager's configuration {"GatewayV1Gateway": {"name":"kong","namespace":"default"}, "namespace": "default", "name": "kong", "service": "kong/kong-proxy", "error": "publish service reference \"kong/kong-proxy\" from Gateway's annotations did not match configured controller manager's publish services (\"kong/new-kong-proxy\")"}