From 0d4d8cceca1bc1e0ae7356124f03b538b36b665d Mon Sep 17 00:00:00 2001 From: Mattia Lavacca Date: Thu, 2 Mar 2023 17:30:19 +0100 Subject: [PATCH] docs: GRPCRoute guide (#5216) docs: GRPCRoute guide added Signed-off-by: Mattia Lavacca --- .../guides/using-ingress-with-grpc.md | 183 +++++++++++++++++- .../references/gateway-api-support.md | 10 + 2 files changed, 192 insertions(+), 1 deletion(-) diff --git a/app/_src/kubernetes-ingress-controller/guides/using-ingress-with-grpc.md b/app/_src/kubernetes-ingress-controller/guides/using-ingress-with-grpc.md index 5acae2f779c1..44195df66e82 100644 --- a/app/_src/kubernetes-ingress-controller/guides/using-ingress-with-grpc.md +++ b/app/_src/kubernetes-ingress-controller/guides/using-ingress-with-grpc.md @@ -1,7 +1,9 @@ --- -title: Using Ingress with gRPC +title: Exposing a gRPC service +content_type: tutorial --- +{% if_version lte:2.8.x %} ## Installation Please follow the [deployment](/kubernetes-ingress-controller/{{page.kong_version}}/deployment/overview/) documentation to install @@ -86,3 +88,182 @@ talks to the upstream service: ```bash grpcurl -v -d '{"greeting": "Kong Hello world!"}' -insecure $PROXY_IP:443 hello.HelloService.SayHello ``` +{% endif_version %} + +{% if_version gte:2.9.x %} +## Overview + +This guide walks through deploying a simple [Service][svc] that listens for +[gRPC connections][gRPC] and exposes this service outside of the cluster using +{{site.base_gateway}}. + +For this example, you will: +* Deploy a gRPC test application. +* Route gRPC traffic to it using Ingress or GRPCRoute. + +{% include_cached /md/kic/installation.md kong_version=page.kong_version %} + +{% include_cached /md/kic/class.md kong_version=page.kong_version %} + +[svc]:https://kubernetes.io/docs/concepts/services-networking/service/ +[gRPC]:https://grpc.io/ + +## Prerequisite + +To make `gRPC` requests, you need a client that can invoke gRPC requests. +In this guide, we use +[`grpcurl`](https://github.com/fullstorydev/grpcurl#installation). +Ensure that you have it installed on your local system. + +## Deploy a gRPC test application + +Add a gRPC deployment and service: + +```bash +echo "--- +apiVersion: v1 +kind: Service +metadata: + name: grpcbin + labels: + app: grpcbin +spec: + ports: + - name: grpc + port: 443 + targetPort: 9001 + selector: + app: grpcbin +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: grpcbin +spec: + replicas: 1 + selector: + matchLabels: + app: grpcbin + template: + metadata: + labels: + app: grpcbin + spec: + containers: + - image: moul/grpcbin + name: grpcbin + ports: + - containerPort: 9001 +" | kubectl apply -f - +``` +Response: +```text +deployment.apps/grpcbin created +service/grpcbin created +``` + +## Route GRPC traffic + +Now that the test application is running, you can create GRPC routing configuration that +proxies traffic to the application: + +{% navtabs api %} +{% navtab Ingress %} +```bash +echo "apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: demo + annotations: + kubernetes.io/ingress.class: kong +spec: + rules: + - http: + paths: + - path: / + backend: + serviceName: grpcbin + servicePort: 443" | kubectl apply -f - +``` +Response: +```text +ingress.networking.k8s.io/demo created +``` +{% endnavtab %} +{% navtab Gateway APIs %} +```bash +echo "apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GRPCRoute +metadata: + name: grpcbin +spec: + parentRefs: + - name: kong + hostnames: + - example.com + rules: + - backendRefs: + - name: grpcbin + port: 443 +" | kubectl apply -f - +``` +Response: +```text +grpcroute.gateway.networking.k8s.io/demo created +``` +{% endnavtab %} +{% endnavtabs %} + +## Update the Ingress rule + +Next, if using the ingress, we need to update the Ingress rule to specify gRPC as the protocol. +By default, all routes are assumed to be either HTTP or HTTPS. This annotation +informs Kong that this route is a gRPC(s) route and not a plain HTTP route: + +{% navtabs api %} +{% navtab Ingress %} +```bash +kubectl patch ingress demo -p '{"metadata":{"annotations":{"konghq.com/protocols":"grpc,grpcs"}}}' +``` +{% endnavtab %} +{% endnavtabs %} + +We also need to update the upstream protocol to be `grpcs`. +Similar to routes, Kong assumes that services are HTTP-based by default. +With this annotation, we configure Kong to use gRPCs protocol when it +talks to the upstream service: + +{% navtabs api %} +{% navtab Ingress %} +```bash +kubectl patch svc grpcbin -p '{"metadata":{"annotations":{"konghq.com/protocol":"grpcs"}}}' +``` +{% endnavtab %} +{% endnavtabs %} + +## Test the configuration + +First, retrieve the external IP address of the Kong proxy service: + +```bash +export PROXY_IP="$(kubectl -n kong get service kong-proxy \ + -o=go-template='{% raw %}{{range .status.loadBalancer.ingress}}{{.ip}}{{end}}{% endraw %}')" +``` + +After, use `grpcurl` to send a gRPC request through the proxy: + +{% navtabs codeblock %} +{% navtab Command %} +```bash +grpcurl -d '{"greeting": "Kong"}' -servername example.com -insecure $PROXY_IP:443 hello.HelloService.SayHello +``` +{% endnavtab %} +{% navtab Response %} +```text +{ + "reply": "hello Kong" +} +``` +{% endnavtab %} +{% endnavtabs %} +{% endif_version %} diff --git a/app/_src/kubernetes-ingress-controller/references/gateway-api-support.md b/app/_src/kubernetes-ingress-controller/references/gateway-api-support.md index a115b1d719cb..3dad69624f94 100644 --- a/app/_src/kubernetes-ingress-controller/references/gateway-api-support.md +++ b/app/_src/kubernetes-ingress-controller/references/gateway-api-support.md @@ -86,6 +86,12 @@ The {{site.kic_product_name}} supports the following resources and features in t - Supported `v1alpha2` of TLSRoute. +## GRPC Routes + +### v2.9.x + +- Supported `v1alpha2` of GRPCRoute. + ## Reference Grants and Reference Policies ### v2.4.x @@ -96,3 +102,7 @@ The {{site.kic_product_name}} supports the following resources and features in t ### v2.6.x - Supported `v1alpha2` version of ReferenceGrant and removed support of ReferencePolicy. + +### v2.9.x + +- Supported `v1beta1` version of ReferenceGrant, and removed support of `v1alpha2` version ReferenceGrant.