diff --git a/docs/latest/user/grpc-routing.md b/docs/latest/user/grpc-routing.md new file mode 100644 index 00000000000..0cdce78a130 --- /dev/null +++ b/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 diff --git a/docs/latest/user_docs.rst b/docs/latest/user_docs.rst index 8fa58c4c733..23a801d6833 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 diff --git a/examples/kubernetes/grpc-routing.yaml b/examples/kubernetes/grpc-routing.yaml new file mode 100644 index 00000000000..388dc09aa4f --- /dev/null +++ b/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