End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Management Suite API Connectivity Manager Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing API Connectivity Manager Module customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

Publish a gRPC API Proxy

Learn how to use NGINX Management Suite API Connectivity Manager to publish a gRPC Proxy and manage traffic to gRPC services.

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`

{
    "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`

{
    "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`

{
    "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`

{
    "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:

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

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

syntax = "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:

import 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.