Google Cloud Platform ESPv2

The src/api_proxy directory contains the core business logic for ESPv2. This logic is designed to be invoked by HTTP Filters.

Important Integration Rule: When using code from this directory, any logic that is specific to Envoy (the underlying proxy) should be abstracted away before calling the ESPv2 business logic. This ensures that the core business logic remains decoupled from the specific proxy implementation.

ESPv2 supports JWT Authentication by converting OpenAPI definitions into Envoy filters:

• Providers: Created from OpenAPI securityDefinitions.
• Requirements: Created from OpenAPI per-path security rules.

ESPv2 requires an OpenAPI Specification v2.0 document to define the service surface and routing. To link the proxy to your backend, you must modify your OpenAPI document with two specific fields:

1. host: Set this to the PROXY_SERVICE_URL (the URL of your ESPv2 Cloud Run service) without the protocol (e.g., my-proxy-service.a.run.app).
2. x-google-backend: Add this object containing the address field, which must be the BACKEND_SERVICE_URL (the URL of your backend Cloud Run service) with the protocol (e.g., https://my-backend-service.a.run.app).

{
  "host": "PROXY_SERVICE_URL",
  "x-google-backend": {
    "address": "https://BACKEND_SERVICE_URL"
  }
}

The Service Control Filter integrates with Google Service Infrastructure to manage API requests. It uses the Google Service Control REST API to perform the following functions for incoming API requests:

• Authentication: Verifying the identity of the API consumer.
• Rate-limiting: Enforcing quota and rate limits.
• Metrics Reporting: Sending usage data to Google Service Control.
• Logging: Creating audit logs for API requests.

The Backend Auth Filter enables authorization when sending requests to backends via Dynamic Routing. When authentication is configured within a backend rule, this filter automatically overwrites the Authorization header with the appropriate identity token.

Important Behavior: This is a pass-through filter. If the requested operation is not explicitly configured in the filter configuration, the request will pass through the proxy unmodified.

ESPv2 is the successor to the original ESP (which used an nginx-based data plane). ESPv2 uses Envoy and is designed to be mostly backwards-compatible.

• Compatibility: API producers generally do not need to modify the Endpoints Service Configuration.
• Exceptions: There are a few incompatible startup flags.
• Recommendation:
  • For serverless reverse proxy deployments, use ESPv2 instead of ESP.
  • For sidecar deployments, ESPv2 is recommended as it receives more features.

For detailed migration steps, consult the official migration guide.

The gRPC Metadata Scrubber Filter is an Envoy filter designed to prevent the accidental dropping of gRPC trailers in specific HTTP/1.1 deployment scenarios.

When a response has a content-type of application/grpc, the filter checks for the presence of a content-length header. If content-length is found, the filter removes it.

This is necessary because Envoy's downstream HTTP/1 codec follows RFC 7230, which dictates that gRPC trailers are dropped if the response headers include a content-length. By scrubbing the content-length header, the filter allows gRPC trailers to be retained when using chunked encoding (often used by downstream clients to transport gRPC over HTTP/1).

When using ESPv2 as an API Gateway, the Google OpenAPI x-google-backend extension is automatically converted into the following Envoy components:

• Route Configuration: Handles host rewrites to the remote backend.
• Path Rewrite Filter: Handles path rewrites to the remote backend.
• Backend Auth Filter: Handles authentication with the remote backend.