Migrate discovered gRPC upstreams to 1.14
Gloo Gateway version 1.14.0 introduced significant changes to the gRPC API that changes the behavior for how gRPC upstreams are discovered. If you have existing gRPC services that were discovered by a previous version of Gloo Gateway, and you want to continue to automatically discover new gRPC services and keep track of any changes to those services, migrate to the new gRPC API.
Before you begin
In previous versions of Gloo Gateway, you added any HTTP to gRPC mappings to the virtual service. With Gloo Gateway 1.14.0, the mappings on the virtual services are no longer discovered automatically. Instead, HTTP mappings must always be provided in the proto itself.
Starting in Gloo Gateway OSS version 1.14.4 (Gloo Gateway Enterprise version 1.14.2), virtual services that still define the destinationSpec: grpc
section can route to gRPC upstreams that are already migrated to the new gRPC API.
This migration guide assumes that you want to use Gloo Gateway to automatically discover the gRPC upstreams. If you do not want to automatically discover the proto descriptors on your gRPC upstreams, you can manually add the proto descriptors. Follow this guide to learn how to generate proto descriptors and add them to the upstream.
-
Check if you have gRPC upstreams that must be migrated to the new API. gRPC upstreams that were discovered by a previous Gloo Gateway version define the
serviceSpec: grpc
section and configured any HTTP mappings in thedestinationSpec: grpc
section of the corresponding virtual service. -
Review how gRPC transcoding works in Gloo Gateway 1.14.
-
Add the HTTP mappings to your protos. Refer to the transcoding reference to learn how to map gRPC functions to HTTP methods. As you update your protos, keep the following things in mind:
- In order for the migration and for Gloo Gateway to automatically discover the HTTP mappings, the descriptors that are exposed on your gRPC service must match the routes on your existing virtual services.
Using the bookstore example, if
GetShelf
is mapped to/shelves/{shelf}
with the followingdestinationSpec
:routeAction: single: destinationSpec: grpc: function: GetShelf package: main service: Bookstore parameters: path: /shelves/{shelf}
Then the proto must be defined as follows:
rpc GetShelf(GetShelfRequest) returns (Shelf) { option (google.api.http) = { get: "/shelves/{shelf}" }; }
- The old API ignored
body:
options in the descriptors and always used a wildcard. To ensure a 1:1 mapping between request bodies when migrating to the new API, your descriptors must also use wildcards for the request body as shown in theCreateShelf
method in the following Bookstore example. For more information about using a wildcard in the request body, see Use wildcard in body.// Creates a new shelf in the bookstore. rpc CreateShelf(CreateShelfRequest) returns (Shelf) { option (google.api.http) = { post: "/shelf" body: "*" }; }
- In order for the migration and for Gloo Gateway to automatically discover the HTTP mappings, the descriptors that are exposed on your gRPC service must match the routes on your existing virtual services.
Using the bookstore example, if
Migrate to the new gRPC API
Migrate your upstreams to the new gRPC API. During the migration, your routes to the gRPC services continue to work.
- Review the upgrade notices for Gloo Gateway 1.14.
- Prepare your Helm chart for the upgrade to 1.14. Make sure to enable the Gloo Gateway function discovery (FDS) feature. For more information, see Configuring the fdsMode Setting.
- Upgrade your installation to 1.14. Make sure to apply any new CRDs.
- Delete the existing gRPC upstreams that were discovered by a previous version of Gloo Gateway.
kubectl delete upstream <upstream_name> -n gloo-system
- Wait a few seconds. Then, verify that the gRPC upstreams were automatically discovered by Gloo Gateway again.
kubectl get upstreams -n gloo-system
- Update the corresponding virtual services and remove the
destinationSpec: grpc
section. Note that with Gloo Gateway OSS version 1.14.4 (Gloo Gateway Enterprise version 1.14.2), virtual services that keep thedestinationSpec: grpc
section can still route to gRPC upstreams that were migrated to the new gRPC API.