Cloud Endpoints: Architectural Overview

Google Cloud Endpoints is a distributed API Management system comprising services, runtimes, and tools. Cloud Endpoints, configured using the OpenAPI Specification, provides management, monitoring, and authentication.

The components that make up Google Cloud Endpoints are:

  • Extensible Service Proxy - for injecting Google Cloud Endpoints functionality

  • Google Service Control - for applying API management rules

  • Google Service Management - for configuring API management rules

  • Google Cloud SDK - for deploying and management

  • Google Cloud Console - for logging, monitoring and sharing

Cloud Endpoints Architecture

Cloud Endpoints architecture

Cloud Endpoints Components

Extensible Service Proxy

The Extensible Service Proxy is a NGINX-based proxy that runs in front of the backend and injects Cloud Endpoints functionality such as authentication, monitoring and logging. The proxy retrieves a service configuration from Google Service Management and uses it to perform validation on incoming requests.

The proxy is designed to be deployed in a containerized environment and validate JWTs and Google ID tokens. It employs a variety of techniques such as heavy caching and asynchronous calls to remain lightweight and highly performant.

Google Service Control

Service Control applies API management rules at runtime such as key authentication, monitoring, and logging. It has two main features:

  • Check - verifies authentication and API keys, and indicates whether a call should be permitted

  • Report - notifies the systems of record for logging and monitoring

Google Service Management

Cloud Endpoints uses the OpenAPI specification to describe an API. Deploying this specification to Service Management - typically using Google Cloud SDK - configures the API management rules. Other configuration related tasks also happen here, such as sharing your API with other developers, enabling/disabling the API in different projects, and generating API keys.

Google Cloud SDK

Cloud SDK provides the gcloud command-line application that can be used to make calls to various services of Google Cloud Platform. The gcloud command-line tool is also used to deploy your API Configuration to Service Management.

Google Cloud Console

Cloud Console is the graphical user interface for Google Cloud Platform. Cloud Endpoints uses Cloud Console to expose monitoring and logging data that are sent from the proxy and recorded by Service Control and share APIs with other developers, and for them to generate API keys to call the API.

Deployment Scenarios

The proxy is designed to be deployed in a container alongside each instance of your backend. This server-local topology is ideal for both web-facing APIs as well as microservices. It avoids the network hop typically associated with centralized proxies and allows API management that is very highly performant as well as extremely scalable.

Typically, load balancing is applied before traffic hits the proxy. On Google Compute Engine it is accomplished via Google Cloud Load Balancer. For Kubernetes deployments, an ingress proxy can be used for load balancing. In Google GKE, either a Google Cloud Load Balancer or ingress proxy can be used for load balancing.

Upon startup, the proxy obtains its service configuration from Service Management. The service configuration is generated from the OpenAPI specification or from gRPC, the service configuration YAML file. It tells the proxy both the surface of the API to be managed along with the policies, such as which methods require authentication, and which require API keys.

Request Routing

When a request is received, the proxy creates a trace token for Stackdriver Trace.

Next, the proxy matches the path of the incoming requests with the surface of the API. If it does not match a known route, the proxy checks the configuration to see if unknown routes are permitted and rejects the request if they are not. Logging information for the rejected request is sent to the Service Control API.

After finding a matching route, the proxy performs any authentication steps for the specified method.

If JWT validation is necessary, the proxy validates the authentication using the appropriate public key for the signer, and validating the audience field in the JWT. If an API key is required, the proxy calls the Service Control API to validate the key.

Service Control looks up the key to validate it, and ensures that the project associated with the key has enabled the API. If the key is not valid or the project has not enabled the API, the call is rejected and it is logged via the Service Control API.

If Service Control successfully validates the key, the request along with all original headers, plus a JWT validation header, if appropriate, is forwarded to the backend.

When a response is received from the backend, the proxy returns the response to the caller and sends the final timing information to Stackdriver Trace. The callpoints are logged via the Service Control API, which writes metrics and logs to their appropriate destinations.

ESP on Kubernetes

The following diagram shows the overall architecture where Extensible Service Proxy runs as a side-car container in front of the API service application container, with my-api API hosted at and backed by a Kubernetes Service.

Endpoints on Kubernetes overview

Further reading

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints with gRPC
Need help? Visit our support page.