Example of using nginx-ingress with gRPC

docs/examples/grpc/README.md

@@ -0,0 +1,105 @@
+# gRPC
+
+This example demonstrates how to route traffic to a gRPC service through the
+nginx controller.
+
+## Prerequisites
+
+1. You have a kubernetes cluster running.
+2. You have a domain name such as `example.com` that is configured to route
+   traffic to the ingress controller.  Replace references to
+   `fortune-teller.stack.build` (the domain name used in this example) to your
+   own domain name (you're also responsible for provisioning an SSL certificate
+   for the ingress).
+3. You have the nginx-ingress controller installed in typical fashion (must be
+   at least
+   [quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.13.0](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller)
+   for grpc support.
+4. You have a backend application running a gRPC server and listening for TCP
+   traffic.  If you prefer, you can use the
+   [fortune-teller](https://github.com/kubernetes/ingress-nginx/images/grpc-fortune-teller)
+   application provided here as an example. 
+
+### Step 1: kubernetes `Deployment`
+
+```sh
+$ kubectl create -f app.yaml
+```
+
+This is a standard kubernetes deployment object.  It is running a grpc service
+listening on port `50051`.
+
+The sample application
+[fortune-teller-app](https://github.com/kubernetes/ingress-nginx/images/grpc-fortune-teller)
+is a grpc server implemented in go. Here's the stripped-down implementation:
+
+```go
+func main() {
+	grpcServer := grpc.NewServer()
+	fortune.RegisterFortuneTellerServer(grpcServer, &FortuneTeller{})
+	lis, _ := net.Listen("tcp", ":50051")
+	grpcServer.Serve(lis)
+}
+```
+
+The takeaway is that we are not doing any TLS configuration on the server (as we
+are terminating TLS at the ingress level, grpc traffic will travel unencrypted
+inside the cluster and arrive "insecure").
+
+For your own application you may or may not want to do this.  If you prefer to
+forward encrypted traffic to your POD and terminate TLS at the gRPC server
+itself, add the ingress annotation `nginx.ingress.kubernetes.io/secure-backends:
+"true"`.
+
+### Step 2: the kubernetes `Service`
+
+```sh
+$ kubectl create -f svc.yaml
+```
+
+Here we have a typical service. Nothing special, just routing traffic to the
+backend application on port `50051`.
+
+### Step 3: the kubernetes `Ingress`
+
+```sh
+$ kubectl create -f ingress.yaml
+```
+
+A few things to note:
+
+1. We've tagged the ingress with the annotation
+   `nginx.ingress.kubernetes.io/grpc-backend: "true"`.  This is the magic
+   ingredient that sets up the appropriate nginx configuration to route http/2
+   traffic to our service.
+1. We're terminating TLS at the ingress and have configured an SSL certificate
+   `fortune-teller.stack.build`.  The ingress matches traffic arriving as
+   `https://fortune-teller.stack.build:443` and routes unencrypted messages to
+   our kubernetes service.
+
+### Step 4: test the connection
+
+Once we've applied our configuration to kubernetes, it's time to test that we
+can actually talk to the backend.  To do this, we'll use the
+[grpcurl](https://github.com/fullstorydev/grpcurl) utility:
+
+```sh
+$ grpcurl fortune-teller.stack.build:443 build.stack.fortune.FortuneTeller/Predict
+{
+  "message": "Let us endeavor so to live that when we come to die even the undertaker will be sorry.\n\t\t-- Mark Twain, \"Pudd'nhead Wilson's Calendar\""
+}
+```
+
+### Debugging Hints
+
+1. Obviously, watch the logs on your app.
+2. Watch the logs for the nginx-ingress-controller (increasing verbosity as
+   needed).
+3. Double-check your address and ports.
+4. Set the `GODEBUG=http2debug=2` environment variable to get detailed http/2
+   logging on the client and/or server.
+5. Study RFC 7540 (http/2) <https://tools.ietf.org/html/rfc7540>.
+
+> If you are developing public gRPC endpoints, check out
+> https://proto.stack.build, a protocol buffer / gRPC build service that can use
+> to help make it easier for your users to consume your API.