Proxyless gRPC limitations

This document describes limitations that apply to Traffic Director with proxyless gRPC applications. For information about limits, see Quotas and limits.

General limitations

The limitations of Traffic Director with proxyless gRPC applications include the following:

• You cannot configure backend services and routing rule maps with the gRPC protocol in the Google Cloud console. For these resources, the Google Cloud console is read-only.

• Proxyless gRPC supports endpoint discovery, routing, load balancing, load reporting, and many advanced traffic management features.

  • For the minimum gRPC version required to support some advanced traffic management features, see Supported gRPC versions and languages.

  • For your gRPC applications that need unsupported advanced traffic management features, use the DNS name resolver instead of the xDS resolver and deploy with sidecar proxies that are supported with Traffic Director. In your target gRPC proxy, set the validateForProxyless field to FALSE so that you can configure features that are not yet supported by gRPC but that are available in Traffic Director with the use of sidecar proxies.

• Proxyless gRPC supports only round-robin and ring hash load balancing policies. Other load-balancing policies are not supported.

  • Traffic Director provides a prioritized weighted list of localities—one instance group or one network endpoint group (NEG)—to the gRPC client. Traffic Director calculates this list based on the closest available zone, its capacity, and the balancing mode of the backend service.
  • For a particular request, the gRPC client picks one or more localities based on the priority and weight and does round-robin or ring hash-based load balancing to the backends within those localities.

• The failover from one zone (locality) to another starts when the current zone capacity falls below 50%. You can't configure this threshold.

• In some cases, the configuration commands related to a target gRPC proxy and a forwarding rule that references a target gRPC proxy might take up to a minute.

• Hybrid connectivity NEGs (NON_GCP_PRIVATE_IP_PORT NEGs) are not supported with proxyless gRPC clients.

URL map limitations

The following URL map traffic management features are supported with proxyless gRPC services.

Features supported in the pathMatcher of hostRules:

pathMatcher
  name
  description
  defaultService
  defaultRouteAction
     weightedBackendServices
       backendService
       weight
    retryPolicy
       retryConditions
       numRetries
    faultInjectionPolicy
    maxStreamDuration
  pathRules
    service
    routeAction
      weightedBackendServices
         backendService
         weight
      retryPolicy
         retryConditions
         numRetries
      faultInjectionPolicy
      maxStreamDuration
    paths
  routeRules
    priority
    description
    matchRules
        prefixMatch
        fullPathMatch
        headerMatches
        metadataFilters
    service
    routeAction
      weightedBackendServices
         backendService
         weight
      retryPolicy
         retryConditions
         numRetries
      faultInjectionPolicy
      maxStreamDuration

The following URL map limitations apply when you use proxyless gRPC services:

• Wildcard characters in the host rules and default rules of a URL map, including the implicitly created * host rule of a URL map, are not supported. Such entries are skipped when host matching is done.

• The following features are not supported:

  • queryParameterMatches in routeRules
  • headerAction, urlRewrite, requestMirrorPolicy, corsPolicy, and urlRedirect route actions
  • timeout route action; use maxStreamDuration instead of timeout
  • perTryTimeout in retryPolicy
  • retryConditions in retryPolicy except one or more conditions of cancelled, deadline-exceeded, internal, resource-exhausted, and unavailable
  • The defaultService, defaultRouteAction, defaultUrlRedirect, and headerAction of the URL map are not used by proxyless gRPC services. If a matching host rule is not found when a proxyless gRPC client looks up a service name, Traffic Director returns a name lookup error instead of using the default service or action of the URL map.
  • headerAction in weightedBackendServices

• In URL map header match rules, only non-binary user-specified custom metadata and the content-type header are supported. The following transport-level headers cannot be used in header matching rules: :authority, :method, :path, :scheme, user-agent, accept-encoding, content-encoding, grpc-accept-encoding, grpc-encoding, grpc-previous-rpc-attempts, grpc-tags-bin, grpc-timeout, and grpc-trace-bin.

• When you update a URL map host rule to change from one backend service to another, traffic might be dropped momentarily while the new configuration is pushed to the clients. To avoid this limitation, configure traffic splitting with weighted backend services. After configuring traffic splitting, slowly shift traffic from the old backend service to the new backend service.

Target gRPC proxy limitations

When a target gRPC proxy references a URL map, you cannot configure the following URL map features. This is true whether you are using a sidecar proxy or a proxyless gRPC service because these HTTP protocol-specific features do not apply to the gRPC protocol:

• queryParameterMatches match rule
• urlRewrite route action
• urlRedirect route action
• corsPolicy action

Backend service limitations

The following backend service features are not supported with proxyless gRPC services that are supported with a sidecar proxy:

• localityLbPolicy except LEAST_REQUEST (with Java clients only), ROUND_ROBIN, and RING_HASH
• sessionAffinity except HEADER_FIELD and NONE
• consistentHash except the httpHeaderName and minimumRingSize fields
• affinityCookieTtlSec
• timeoutSec; use maxStreamDuration instead
• circuitBreakers except the maxRequests field

Note: A gRPC client will NACK the configuration from Traffic Director when unsupported values are configured. This will cause configuration for all backend services to be rejected by the client because the xDS protocol currently requires rejecting all resources in a given response, rather than being able to reject only an individual resource from the response. This will cause the client channel to go into a transient error state until the configuration is fixed. Due to this limitation, you must ensure that all clients support the required value before configuring a feature for a service. For example, if you change the ROUND_ROBIN policy to RING_HASH, you must ensure that all the clients are upgraded to a version that supports RING_HASH.

Advanced traffic management limitations

You can't configure some advanced traffic management features for proxyless gRPC services with Traffic Director. For supported features, see the following:

• Supported gRPC versions and languages
• Traffic Director features, including load balancing

Limitations with Service Directory

• Service Directory and Traffic Director do not guarantee network reachability for clients.

• A backend service can only reference one of the following:

  • Managed instance group or unmanaged instance group
  • Network endpoint group
  • Service bindings

• Service Directory services can only be used with global backend services with load-balancing-scheme=INTERNAL_SELF_MANAGED.

• A Service Directory service that is referenced by a service binding can be deleted. If the underlying Service Directory service to which the backend service is attached is deleted, applications that use Traffic Director cannot send traffic to this service, therefore, requests fail. See Observability and debugging for best practices.

Health checks

When you bind a Service Directory service to a backend service, you cannot configure a health check on the backend service.

What's next

• To learn about limitations that apply to Traffic Director, including advanced traffic management limitations, see Traffic Director limitations.
• To find uses cases and architecture patterns for proxyless gRPC services, see the Proxyless gRPC services overview.