Following this guide, it is possible to release an already existent gRPC service to Kubernetes using the Mia-Platform Console.
gRPC is a modern and open source high performance Remote Procedure Call (RPC) framework incubating by CNCF. The site of gRPC contains all the documentation on what it is, why it should be used and how to start to create your first gRPC service (SDK are available in multiple language).
- a Console project with at least one environment (follow this guide if you want to create it)
- a service using gRPC. In the following use case we use as example YAGES (yet another gRPC echo server)
- a Kubernetes cluster with installed Traefik ingress (the default ingress used in Mia-Platform PaaS)
Add the service
In Console, go to the Microservices section and create a new service from Docker image. Insert
grpc-service as name and the docker image of the selected gRPC service.
Once created, modify this information:
- API documentation path: remove the default path to avoid to fetch the documentation (since the fetch use http API);
- remove the probes path from the Runtime section (both Readiness and Liveness)
- remove all the Environment Variables except the
HTTP_PORTenv var, and set as value the port exposed by the service
Use inside the cluster
Test with port-forward
This step is possible only if your user has the permission on the Kubernetes cluster to port-forward in the specified namespace.
Copy the following command and change
MY_NAMESPACE with the namespace where you have deployed the project.
kubectl -n MY_NAMESPACE port-forward svc/grpc-service 9000:80
Once the grpc-service is exposed locally, you can contact it with the grpcurl
grpcurl --plaintext localhost:9000 yages.Echo.Ping
and you should obtain the response
From outside the cluster
With Envoy as Api Gateway and Traefik as ingress
To expose the server with the Envoy API Gateway, you can create an endpoint on
/ which point to the
It is possible to expose a specific endpoint pointing to the correct microservice.
To contact the API, the client must have the
.proto file loaded. Otherwise, the client try to contact the reflection method of the server, but it use a specific endpoint.
To expose an endpoint, remember that it is created from the method called. So, if we call the method
yages.Echo.Ping, the path colled will be
/yages.Echo/Ping. It is possible from the Console to expose an endpoint with basePath set to
/yages.Echo and the rewritePath to
/yages.Echo, and it works.
gRPC is based on http2, so the cluster created in envoy must use http2. To configure so, from the advanced section in design area, open the
api-gateway-envoy/clusters.yaml file. This file can overwrite the clusters configuration (see here the docs).
http2_protocol_options is the option necessary to make it works correctly, so you should add the following configuration:
- "@type": type.googleapis.com/envoy.config.cluster.v3.Cluster
It is now possible to test it using the port forward configuration method as showed in the test with port-forward section.
You should only change the port-forward command (if your API Gateway is created from Mia-Platform marketplace and the name of the service is
kubectl -n MY_NAMESPACE port-forward svc/api-gateway 8080:80
To expose a gRPC endpoint from the cluster with traefik, it is necessary to add the scheme h2c to the IngressRoute resource.
In the following example, the match is to the host
MY_HOST. Under the services field, note that the scheme is set to h2c. This is the configuration required to make the gRPC call works.
- match: Host(`MY_HOST`)
- name: "ingress-controller-hsts-headers"
- name: api-gateway
It is possible to test the connection (sobstitute MY_HOST with your host, remember to add the default port 443 if not already set a port in MY_HOST):
grpcurl MY_HOST yages.Echo.Ping
The scheme h2c works with envoy also with rest API