From 86c77f39c3bf2ed7f78490398a377e43faaf7639 Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Thu, 2 Feb 2023 17:02:58 -0800 Subject: [PATCH 1/6] Add docs for GRPCRoute Fixes: https://github.com/envoyproxy/gateway/issues/642 Signed-off-by: Arko Dasgupta --- docs/latest/user/grpc-routing.md | 99 +++++++++++++++++++++++++++ examples/kubernetes/grpc-routing.yaml | 82 ++++++++++++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 docs/latest/user/grpc-routing.md create mode 100644 examples/kubernetes/grpc-routing.yaml diff --git a/docs/latest/user/grpc-routing.md b/docs/latest/user/grpc-routing.md new file mode 100644 index 0000000000..61e4244868 --- /dev/null +++ b/docs/latest/user/grpc-routing.md @@ -0,0 +1,99 @@ +# GRPC Routing + +The [GRPCRoute][] resource allows users to configure gRPC routing by matching HTTP/2 traffic and forwarding it to backend gRPC servers. +To learn more about gRPC routing, refer to the [Gateway API documentation][]. + +## Prerequisites + +Install Envoy Gateway: + +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/install.yaml +``` + +Wait for Envoy Gateway to become available: + +```shell +kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available +``` + +## Installation + +Install the gRPC routing example resources: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/http-routing.yaml +``` + +The manifest installs a [GatewayClass][], [Gateway][], a Deployment, a Service, and a GRPCRoute resource. +The GatewayClass is a cluster-scoped resource that represents a class of Gateways that can be instantiated. + +__Note:__ Envoy Gateway is configured by default to manage a GatewayClass with +`controllerName: gateway.envoyproxy.io/gatewayclass-controller`. + +## Verification + +Check the status of the GatewayClass: + +```shell +kubectl get gc --selector=example=grpc-routing +``` + +The status should reflect "Accepted=True", indicating Envoy Gateway is managing the GatewayClass. + +A Gateway represents configuration of infrastructure. When a Gateway is created, [Envoy proxy][] infrastructure is +provisioned or configured by Envoy Gateway. The `gatewayClassName` defines the name of a GatewayClass used by this +Gateway. Check the status of the Gateway: + +```shell +kubectl get gateways --selector=example=grpc-routing +``` + +The status should reflect "Ready=True", indicating the Envoy proxy infrastructure has been provisioned. The status also +provides the address of the Gateway. This address is used later in the guide to test connectivity to proxied backend +services. + +Check the status of the GRPCRoute: + +```shell +kubectl get httproutes --selector=example=grpc-routing -o yaml +``` + +The status for the GRPCRoute should surface "Accepted=True" and a `parentRef` that references the example Gateway. +The `example-route` matches any traffic for "grpc-example.com" and forwards it to the "yages" Service. + +## Testing the Configuration + +Before testing GRPC routing to the `yages` backend, get the Gateway's address. + +```shell +export GATEWAY_HOST=$(kubectl get gateway/example-gateway -o jsonpath='{.status.addresses[0].value}') +``` + +Test GRPC routing to the `yages` backend using the `grpcurl` command. + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +You should see the below response +``` +{ + "text": "pong" +} +``` + +Envoy Gateway also supports [gRPC-Web][] requests for this configuration. The below `curl` command can be used to send a grpc-Web request with over HTTP/2. You should receive the same response seen in the previous command. + +```shell +curl --http2-prior-knowledge -s ${GATEWAY_HOST}:80/yages.Echo/Ping -H 'Host: grpc-example.com' -H 'Content-Type: application/grpc-web-text' -H 'Accept: application/grpc-web-text' -XPOST -d'AAAAAAA=' | base64 -d +``` + + +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[GatewayClass]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/ +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[Envoy proxy]: https://www.envoyproxy.io/ +[gRPC-Web]: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2 +[spec]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRoute diff --git a/examples/kubernetes/grpc-routing.yaml b/examples/kubernetes/grpc-routing.yaml new file mode 100644 index 0000000000..8a63746b21 --- /dev/null +++ b/examples/kubernetes/grpc-routing.yaml @@ -0,0 +1,82 @@ +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: GatewayClass +metadata: + name: example-gateway-class + labels: + example: grpc-routing +spec: + controllerName: gateway.envoyproxy.io/gatewayclass-controller +--- +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: Gateway +metadata: + name: example-gateway + labels: + example: grpc-routing +spec: + gatewayClassName: example-gateway-class + listeners: + - name: http + protocol: HTTP + port: 80 +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: yages + example: grpc-routing + name: yages +spec: + selector: + matchLabels: + app: yages + example: grpc-routing + replicas: 1 + template: + metadata: + labels: + app: yages + spec: + containers: + - name: grpcsrv + image: quay.io/mhausenblas/yages:0.1.0 + ports: + - containerPort: 9000 + protocol: TCP +--- +apiVersion: v1 +kind: Service +metadata: + labels: + app: yages + example: grpc-routing + name: yages +spec: + type: ClusterIP + ports: + - name: http + port: 9000 + protocol: TCP + targetPort: 9000 + selector: + app: yages +--- +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GRPCRoute +metadata: + name: yages + labels: + example: grpc-routing +spec: + parentRefs: + - name: eg + hostnames: + - "grpc-example.com" + rules: + - backendRefs: + - group: "" + kind: Service + name: yages + port: 9000 + weight: 1 From 8bbb74f8c909719c5c07b4a1293f0f4f9e52cb52 Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Thu, 2 Feb 2023 17:30:20 -0800 Subject: [PATCH 2/6] typo Signed-off-by: Arko Dasgupta --- docs/latest/user/grpc-routing.md | 4 ++-- examples/kubernetes/grpc-routing.yaml | 31 +++++++++++++-------------- 2 files changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/latest/user/grpc-routing.md b/docs/latest/user/grpc-routing.md index 61e4244868..ce607dcc64 100644 --- a/docs/latest/user/grpc-routing.md +++ b/docs/latest/user/grpc-routing.md @@ -22,7 +22,7 @@ kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for Install the gRPC routing example resources: ```shell -kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/http-routing.yaml +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/grpc-routing.yaml ``` The manifest installs a [GatewayClass][], [Gateway][], a Deployment, a Service, and a GRPCRoute resource. @@ -56,7 +56,7 @@ services. Check the status of the GRPCRoute: ```shell -kubectl get httproutes --selector=example=grpc-routing -o yaml +kubectl get grpcroutes --selector=example=grpc-routing -o yaml ``` The status for the GRPCRoute should surface "Accepted=True" and a `parentRef` that references the example Gateway. diff --git a/examples/kubernetes/grpc-routing.yaml b/examples/kubernetes/grpc-routing.yaml index 8a63746b21..3b62453deb 100644 --- a/examples/kubernetes/grpc-routing.yaml +++ b/examples/kubernetes/grpc-routing.yaml @@ -31,7 +31,6 @@ spec: selector: matchLabels: app: yages - example: grpc-routing replicas: 1 template: metadata: @@ -39,11 +38,11 @@ spec: app: yages spec: containers: - - name: grpcsrv - image: quay.io/mhausenblas/yages:0.1.0 - ports: - - containerPort: 9000 - protocol: TCP + - name: grpcsrv + image: quay.io/mhausenblas/yages:0.1.0 + ports: + - containerPort: 9000 + protocol: TCP --- apiVersion: v1 kind: Service @@ -55,10 +54,10 @@ metadata: spec: type: ClusterIP ports: - - name: http - port: 9000 - protocol: TCP - targetPort: 9000 + - name: http + port: 9000 + protocol: TCP + targetPort: 9000 selector: app: yages --- @@ -74,9 +73,9 @@ spec: hostnames: - "grpc-example.com" rules: - - backendRefs: - - group: "" - kind: Service - name: yages - port: 9000 - weight: 1 + - backendRefs: + - group: "" + kind: Service + name: yages + port: 9000 + weight: 1 From 6a70333c4b3adbcf80274e36289ddd676fec1ea2 Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Thu, 2 Feb 2023 17:46:39 -0800 Subject: [PATCH 3/6] rm unused link Signed-off-by: Arko Dasgupta --- docs/latest/user/grpc-routing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/latest/user/grpc-routing.md b/docs/latest/user/grpc-routing.md index ce607dcc64..b5ce633eb9 100644 --- a/docs/latest/user/grpc-routing.md +++ b/docs/latest/user/grpc-routing.md @@ -77,7 +77,8 @@ grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Pin ``` You should see the below response -``` + +```shell { "text": "pong" } @@ -96,4 +97,3 @@ curl --http2-prior-knowledge -s ${GATEWAY_HOST}:80/yages.Echo/Ping -H 'Host: grp [Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ [Envoy proxy]: https://www.envoyproxy.io/ [gRPC-Web]: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2 -[spec]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRoute From b82c3914c58d36678a738046cc7a7974ddd8fd62 Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Fri, 3 Feb 2023 18:39:18 -0800 Subject: [PATCH 4/6] fix typo Signed-off-by: Arko Dasgupta --- examples/kubernetes/grpc-routing.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/kubernetes/grpc-routing.yaml b/examples/kubernetes/grpc-routing.yaml index 3b62453deb..388dc09aa4 100644 --- a/examples/kubernetes/grpc-routing.yaml +++ b/examples/kubernetes/grpc-routing.yaml @@ -69,7 +69,7 @@ metadata: example: grpc-routing spec: parentRefs: - - name: eg + - name: example-gateway hostnames: - "grpc-example.com" rules: From 6d664942d99910ca1d5f4458ebcde589c809d340 Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Mon, 6 Feb 2023 10:25:29 -0800 Subject: [PATCH 5/6] add grpcurl link Signed-off-by: Arko Dasgupta --- docs/latest/user/grpc-routing.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/latest/user/grpc-routing.md b/docs/latest/user/grpc-routing.md index b5ce633eb9..0cdce78a13 100644 --- a/docs/latest/user/grpc-routing.md +++ b/docs/latest/user/grpc-routing.md @@ -70,7 +70,7 @@ Before testing GRPC routing to the `yages` backend, get the Gateway's address. export GATEWAY_HOST=$(kubectl get gateway/example-gateway -o jsonpath='{.status.addresses[0].value}') ``` -Test GRPC routing to the `yages` backend using the `grpcurl` command. +Test GRPC routing to the `yages` backend using the [grpcurl][] command. ```shell grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping @@ -96,4 +96,5 @@ curl --http2-prior-knowledge -s ${GATEWAY_HOST}:80/yages.Echo/Ping -H 'Host: grp [GatewayClass]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/ [Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ [Envoy proxy]: https://www.envoyproxy.io/ +[grpcurl]: https://github.com/fullstorydev/grpcurl [gRPC-Web]: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2 From 5db21adcf572a4b9554a94858441bb0076b77510 Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Mon, 6 Feb 2023 14:31:29 -0800 Subject: [PATCH 6/6] link page Signed-off-by: Arko Dasgupta --- docs/latest/user_docs.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/latest/user_docs.rst b/docs/latest/user_docs.rst index 8fa58c4c73..23a801d683 100644 --- a/docs/latest/user_docs.rst +++ b/docs/latest/user_docs.rst @@ -17,3 +17,4 @@ Learn how to deploy, use, and operate Envoy Gateway. user/tls-passthrough user/tcp-routing user/udp-routing + user/grpc-routing