Set Up gRPC Policies

Learn how to use NGINX Management Suite API Connectivity Manager to configure policies for your gRPC API Gateway.


This documentation applies to NGINX Management Suite API Connectivity Manager 1.3.0 and later.

Overview

In NGINX Management Suite API Connectivity Manager (ACM), you can apply global policies to API Gateway and Developer Portal clusters to ensure your organization’s security requirements are enforced.

When you add policies at the environment level, they will apply to all proxies hosted within that environment.

See the Learn about Policies topic for an overview of the different policy types and available policies.

Refer to the Set Up Policies topic for instructions on how to configure policies for your API Gateway and Developer Portal clusters and API Proxies.


Global Policies

Return Default gRPC Status Codes

The default NGINX error pages are suitable for conventional HTTP traffic. gRPC clients, however, expect gRPC responses.

To return default gRPC status codes, send a POST request to the Environments endpoint.

Method Endpoint
POST /infrastructure/workspaces/<INFRA_WORKSPACE_NAME>/environments

Example JSON request
{
    "name": "{{environmentname}}",
    "type": "NON-PROD",
    "functions": [
        "API-GATEWAY"
    ],
    "proxies": [
        {
            "proxyClusterName": "{{instanceGroupName}}",
            "hostnames": [
                "{{environmentHostname}}"
            ],
            "runtime": "GATEWAY-PROXY",
            "listeners": [
                {
                    "port": 8085,
                    "transportProtocol": "GRPC"
                }
            ],
            "policies": {
                "error-response-format": [
                    {
                        "action": {
                            "400": {
                                "errorCode": "13",
                                "grpcStatusCode": 5,
                                "errorMessage": "Bad Request"
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Log Format

Use the following variables to log gRPC-specific information. These variables are enabled by default for gRPC APIs.

Variable Description
grpcMethod The RPC method invoked in the call.
grpcService The service; for example, routeguide.RouteGuide
grpcStatus The gRPC status code returned by the upstream server.
grpcMessage The grpc-message trailer/header

Take note of the following considerations when using these standard log format variables for logging gRPC details:

  • requestURI - This is the relative URI of the gRPC method. The HTTP2 :path pseudo-header is used for this.
  • timestamp - For streaming methods, this value reflects when the stream is closed.
  • totalLatency - For streaming methods, this value reflects the entire duration of the stream.
  • bodySize - For streaming methods, this value counts all of the bytes sent during the duration of the stream and not for individual messages.

Request Body Size Limit

For streaming methods, the request body size limit is enforced on the entire stream, not per individual message. Therefore, we recommend configuring the limit to be very large or disabling this policy altogether for long-lived streams.


API Proxy Policies

Auth Policies

The following policies involve some degree of header reading and modifying depending on their configuration and work the same with gRPC metadata:

  • API Key
  • Basic Auth
  • JWT Assertion
  • OAuth2 Introspection

Select header for any policy setting that configures the supplied-in value.

For example, suppose the Authorization header is used for the API Key authentication, and credential forwarding has been enabled. In that case, the following example Go server code can access that value in the metadata as shown below:

// GetFeature returns the feature at the given point.
func (s *routeGuideServer) GetFeature(ctx context.Context, point *pb.Point) (*pb.Feature, error) {
md, _ := metadata.FromIncomingContext(ctx)
fmt.Printf("Authorization: %+v\n", md.Get("Authorization"))

You can also modify these policies' error return conditions, so they return custom gRPC status codes.

Backend Configuration

There is a separate policy for configuring upstream connection behavior specifically for the gRPC backend service.

  • In the web Interface, select the Backend Config policy.
  • In the REST API, use the grpc-backend-config policy.

By default, the following actions have a configured timeout of 7 days:

  • Reading client request headers (client_header_timeout)
  • Reading client request body (client_body_timeout)
  • Reading a response from the upstream gRPC server (grpc_read_timeout)
  • Transmitting a request to the upstream gRPC server (grpc_send_timeout)

You can configure this policy to override most of these values.

Health Check

gRPC-specific health checking based on the official protocol has yet to be made available.

Conventional HTTP-based health checks can still be configured.

Customize gRPC Status Codes

You can customize the following policies' gRPC status code values:

  • Rate Limit

  • API Key

  • Basic Auth

  • JWT Assertion

  • OAuth2 Introspection

  • ACL IP

  • TLS Inbound

  • Request Body Size Limit

  • In the web interface, any policy which contains Error Handling properties accepts grpcStatusCode rather than HTTP returnCode.

  • In the API, any policy with the errorReturnConditions object that contains a returnCode property, or a returnCode property at the top level, accepts a grpcStatusCode instead of or in addition to returnCode.

    Example JSON request
    "policies": {
        "acl-ip": [
            {
                "action": {
                    "allow": ["10.0.0.2"],
                    "grpcStatusCode": 13
                }
            }
        ]
    }
    

Unsupported Policies

The following policies are not supported at this time:

  • Proxy Cache
  • CORS
  • Allow HTTP Method