diff --git a/app/_data/docs_nav_kic_2.5.x.yml b/app/_data/docs_nav_kic_2.5.x.yml index f227ac5d1e8f..9f3c6c5612c0 100644 --- a/app/_data/docs_nav_kic_2.5.x.yml +++ b/app/_data/docs_nav_kic_2.5.x.yml @@ -33,6 +33,8 @@ items: url: /concepts/security - text: Ingress Resource API Versions url: /concepts/ingress-versions + - text: Gateway API + url: /concepts/gateway-api - title: Deployment icon: /assets/images/icons/documentation/icn-kubernetes-color.svg url: /deployment/overview diff --git a/src/kubernetes-ingress-controller/concepts/gateway-api.md b/src/kubernetes-ingress-controller/concepts/gateway-api.md new file mode 100644 index 000000000000..ecd40f9fd7cc --- /dev/null +++ b/src/kubernetes-ingress-controller/concepts/gateway-api.md @@ -0,0 +1,156 @@ +--- +title: Gateway API +alpha: true +--- + +[Gateway API](https://gateway-api.sigs.k8s.io/) 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 under active +development. Features and implementation specifics will change before their +initial general availability release. + +## Gateway management + +A [Gateway resource](https://gateway-api.sigs.k8s.io/concepts/api-overview/#gateway) +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](/kubernetes-ingress-controller/{{page.kong_version}}/guides/using-gateway-api). + +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: + +``` +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: Gateway +metadata: + name: example +spec: + gatewayClassName: kong + listeners: + - name: proxy + port: 80 + protocol: HTTP + - name: proxy-ssl + port: 443 + protocol: HTTPS + - name: proxy-tcp-9901 + port: 9901 + protocol: TCP + - name: proxy-udp-9902 + port: 9902 + protocol: UDP + - name: proxy-tls-9903 + port: 9903 + protocol: TLS +``` +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 +``` +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 for you from 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 will result 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 + +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 +TCP routes. + +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. diff --git a/src/kubernetes-ingress-controller/guides/using-gateway-api.md b/src/kubernetes-ingress-controller/guides/using-gateway-api.md index 8952f8ca675c..7bbb5647a1d0 100644 --- a/src/kubernetes-ingress-controller/guides/using-gateway-api.md +++ b/src/kubernetes-ingress-controller/guides/using-gateway-api.md @@ -103,9 +103,11 @@ spec: listeners: - name: proxy port: 80 + hostname: kong.example protocol: HTTP - name: proxy-ssl port: 443 + hostname: kong.example protocol: HTTPS " | kubectl apply -f - ``` @@ -113,6 +115,19 @@ spec: ``` gateway.gateway.networking.k8s.io/kong created ``` +{% if_version gte: 2.5.x %} + +This configuration does not load any certificates, and will use a default +self-signed certificate for HTTPS requests. If you have a [TLS +Secret](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets) +you wish to use, you can add it with: + +``` +kubectl patch --type=json gateway kong -p='[{"op":"add","path":"/spec/listeners/1/tls","value":{"certificateRefs":[{"group":"","kind":"Secret","name":"example-cert-secret"}]}}]' +``` + +Change `example-cert-secret` to the name of your Secret. +{% endif_version %} Because KIC and Kong instances are installed independent of their Gateway resource, we set the `konghq.com/gateway-unmanaged` annotation to the @@ -158,6 +173,8 @@ spec: - group: gateway.networking.k8s.io kind: Gateway name: kong + hostnames: + - kong.example rules: - backendRefs: - group: "" @@ -176,7 +193,7 @@ After creating an HTTPRoute, accessing `/echo` forwards a request to the echo service: ```bash -$ curl -i $PROXY_IP/echo +$ curl -i http://kong.example/echo --resolve kong.example:80:$PROXY_IP ``` ``` @@ -209,8 +226,14 @@ Gateway APIs are supported. In particular: {% endif_version %} - queryParam matches matches are not supported. {% if_version gte: 2.4.x %} +{% if_version lte: 2.5.x %} - Gateway Listener configuration does not support TLSConfig. You can't load certificates for HTTPRoutes and TLSRoutes via Gateway configuration, and must either accept the default Kong certificate or add certificates and SNI resources manually via the admin API in DB-backed mode. {% endif_version %} +{% endif_version %} +{% if_version gte: 2.5.x %} +- Gateways [are not provisioned automatically](/kubernetes-ingress-controller/{{page.kong_version}}/concepts/gateway-api#gateway-management). +- Kong [only supports a single Gateway per GatewayClass](/kubernetes-ingress-controller/{{page.kong_version}}/concepts/gateway-api#listener-compatibility-and-handling-multiple-gateways). +{% endif_version %}