Add docs for GRPCRoute (envoyproxy#969)

* Add docs for GRPCRoute

Fixes: envoyproxy#642

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit 3516d10)
Signed-off-by: bitliu <bitliu@tencent.com>

docs/latest/user/grpc-routing.md

@@ -0,0 +1,100 @@
+# 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/grpc-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 grpcroutes --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
+
+```shell
+{
+  "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/
+[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

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

examples/kubernetes/grpc-routing.yaml

@@ -0,0 +1,81 @@
+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
+  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: example-gateway 
+  hostnames:
+    - "grpc-example.com"
+  rules:
+    - backendRefs:
+        - group: ""
+          kind: Service
+          name: yages 
+          port: 9000
+          weight: 1