Publish a gRPC API Proxy

Overview

gRPC has emerged as an alternative approach to building distributed applications, particularly microservice applications. API Connectivity Manager supports publishing gRPC services. The following document describes how to publish a gRPC API proxy using the API Connectivity Manager API or UI. Additionally, this guide outlines the process of setting up a gRPC Echo Server to validate the functionality of the published proxy.

Publish a gRPC API Proxy with Package-level Routing

Send a POST request to publish the gRPC API proxy.

Method	Endpoint
`POST`	`/services/workspaces/<SERVICE_WORKSPACE_NAME>/proxies`

json{
    "name": "dev-grpc-hello",
    "version": "v1",
    "proxyConfig": {
        "hostname": "example.com",
        "grpcIngress": {
            "service": "helloworld."
        },
        "backends": [
          {
            "serviceName": "hello-grpc-service-name",
            "serviceTargets": [
                {
                    "hostname": "grpc-backend.example.com",
                    "listener": {
                        "enableTLS": false,
                        "port": 50051,
                        "transportProtocol": "GRPC"
                    }
                }
            ]
          }
        ]
    }
}

Open a service workspace.
Select Publish to proxy.
Type a Backend Service name.
Enter a Service Target Hostname.
Select GRPC in the Service Target Transport Protocol menu.
Enter the Service Target Port.
Enter an API Proxy name.
Select a Gateway Proxy Hostname in the menu.
Enter the Service name and Version; for this example, we use “helloworld” and “v1”.
Select Publish.

You should now have a published gRPC API proxy with a Lifecycle Status of success.

Publish a gRPC API Proxy with Service-Level Routing

Send a POST request to publish the gRPC proxy.

Method	Endpoint
`POST`	`/services/workspaces/<SERVICE_WORKSPACE_NAME>/proxies`

json{
    "name": "dev-grpc-hello",
    "version": "v1",
    "proxyConfig": {
        "hostname": "example.com",
        "grpcIngress": {
            "service": "helloworld.Greeter"
        },
        "backends": [
          {
            "serviceName": "hello-grpc-service-name",
            "serviceTargets": [
                {
                    "hostname": "grpc-backend.example.com",
                    "listener": {
                        "enableTLS": false,
                        "port": 50051,
                        "transportProtocol": "GRPC"
                    }
                }
            ]
          }
        ]
    }
}

To configure the proxy to route by service:

Open the proxy and select Ingress.
Type “helloWorld.Greeter” in the Service Name field.
Select Save and Publish.

Publish a gRPC API Proxy with Advanced Routes with a gRPC Method

Send a POST request to publish the gRPC proxy.

Method	Endpoint
`POST`	`/services/workspaces/<SERVICE_WORKSPACE_NAME>/proxies`

json{
    "name": "dev-grpc-hello",
    "version": "v1",
    "proxyConfig": {
        "hostname": "example.com",
        "grpcIngress": {
            "service": "helloworld.Greeter",
            "routes": [
                {
                  "method": "SayGoodbye",
                  "targetBackendServiceLabel": "default"
                },
                {
                  "method": "SayHello",
                  "targetBackendServiceLabel": "default"
                }
            ]
        },
        "backends": [
          {
            "serviceName": "hello-grpc-service-name",
            "serviceTargets": [
                {
                    "hostname": "grpc-backend.example.com",
                    "listener": {
                        "enableTLS": false,
                        "port": 50051,
                        "transportProtocol": "GRPC"
                    }
                }
            ]
          }
        ]
    }
}

To configure the proxy with an advanced route

Open the proxy and select the Ingress.
Select Add route and enter the GRPC Method; for example, “SayGoodbye”.
Select Save and Publish.
Proceed to Set Up gRPC Echo Server and Test gRPC API Proxy for the next steps.

Service-Level Routing using Labels

Send a POST request to publish the gRPC proxy.

Method	Endpoint
`POST`	`/services/workspaces/<SERVICE_WORKSPACE_NAME>/proxies`

json{
    "name": "dev-grpc-hello",
    "version": "v1",
    "proxyConfig": {
        "hostname": "example.com",
        "grpcIngress": {
            "service": "helloworld.Greeter",
            "routes": [
                {
                  "method": "SayGoodbye",
                  "targetBackendServiceLabel": "custom"
                },
                {
                  "method": "SayHello",
                  "targetBackendServiceLabel": "default"
                }
            ]
        },
        "backends": [
            {"label": {
              "targetName": "default"
            },
            "serviceName": "hello-grpc-service-name",
            "serviceTargets": [
                {
                    "hostname": "grpc-backend.example.com.1",
                    "listener": {
                        "enableTLS": false,
                        "port": 50051,
                        "transportProtocol": "GRPC"
                    }
                }
            ]
          },
          {
             "label": {
              "targetName": "custom"
            },
            "serviceName": "hello-grpc-service-name",
            "serviceTargets": [
                {
                    "hostname": "grpc-backend.example.com.2",
                    "listener": {
                        "enableTLS": false,
                        "port": 50051,
                        "transportProtocol": "GRPC"
                    }
                }
            ]
          }
        ]
    }
}

If you have multiple backend servers and want to route to a specific backend server, you can use labels.

Open the proxy and select Backend.
Enter a Service Name and Service Version.
Add a label for the backend service, “custom2”.
Type the Service Target Hostname.
Select Add.
Select Save and Publish.
Setup gRPC Echo Server and Test gRPC API Proxy.

Backends

Backends specify where your API should send queries, such as to your backend server.

You can add, edit, or delete backends.

You can also set DNS resolvers and TLS on the backend.

Policies

This section ensures you can set policies at the individual API level.

For more information, refer to the Manage Policies documentation.

Update a Published API Proxy

On the sidebar, select Services. Then on the Services Workspaces page, select the workspace containing the API proxy you want to edit.
Select Edit Proxy from the Actions menu of the Proxy you want to delete.
Edit as needed.
Select Save and Publish.

Delete a Published API Proxy

On the sidebar, select Services. Then on the Services Workspaces page, select the name of the workspace containing the API proxy you want to delete.
Select Delete Proxy from the Actions menu of the Proxy you want to delete.

Set Up gRPC Echo Server (Optional)

This section explains how to set up a gRPC echo server to verify that the gRPC API works as expected.

From a command line terminal:

Create a virtual environment and install the required packages:

shellvirtualenv echo-servers
source echo-servers/bin/activate
pip install grpcio protobuf grpcio-tools

Create a file named helloworld.proto and add the following content:

shellsyntax = "proto3";

package helloworld;

service Greeter {
    rpc SayHello (HelloRequest) returns (HelloReply) {}
    rpc SayGoodbye (GoodbyeRequest) returns (GoodbyeReply) {}
}

message HelloRequest {
    string name = 1;
}

message HelloReply {
    string message = 1;
}

message GoodbyeRequest {
    string name = 1;
}

message GoodbyeReply {
    string message = 1;
}

Run the following command to generate the python code: python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. helloworld.proto

Create server.py Add the following to the file:

shellimport grpc
import helloworld_pb2
import helloworld_pb2_grpc
from concurrent import futures

class GreeterServicer(helloworld_pb2_grpc.GreeterServicer):
    def SayHello(self, request, context):
        response = helloworld_pb2.HelloReply(message='Hello, ' + request.name)
        return response

    def SayGoodbye(self, request, context):
        response = helloworld_pb2.GoodbyeReply(message='Goodbye, ' + request.name)
        return response

def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    helloworld_pb2_grpc.add_GreeterServicer_to_server(GreeterServicer(), server)
    server.add_insecure_port('[::]:50051')
    server.start()
    server.wait_for_termination()

if __name__ == '__main__':
    serve()

Run python server.py.
To confirm the server is running, run the command netstat -tulpn | grep 50051.
For step-by-step instructions on how to set up gRPC testing using Postman, refer to Testing gRPC APIs with Postman. This guide will help you test and validate your gRPC APIs effectively using Postman.

View source

Edit this page

Create a new issue