Apigee Extension Processor - gRPC

This sample demonstrates how to bring Apigee API Management capabilities to your services that currently use Google Cloud Load Balancing. We'll illustrate this integration using a gRPC backend deployed in Cloud Run. The core idea is that you can enhance your existing GCP Load Balancer services by adding a Service Extension, which enables the routing of gRPC (HTTP2) requests and responses through the Apigee Gateway runtime.

With this mechanism, you gain powerful control over your gRPC traffic. This works for both unary, and streaming gRPC services. You can easily add, remove, or modify headers the fly. More importantly, you can apply robust security and governance policies directly to your load-balanced gRPC services. This includes essential features like API Key validation for authentication and authorization, as well as quota enforcement to manage API consumption.

In essence, the Apigee Extension Processor lets you treat your gRPC services as fully managed APIs, leveraging Apigee's comprehensive suite of API management tools without requiring a complete re-architecture. For more information please read the docs on the Apigee Extension Processor and Cloud Load Balancing Service Extensions.

Prerequisites

1. Provision Apigee X
2. Have access to deploy API Proxies in Apigee,
3. Have access to create Environments and Environment Groups in Apigee
4. Have access to create API Products, Developers, and Developer Apps in Apigee
5. Have access to provision Load Balancer Resources (ip address, forwarding rule, url map, backend service, NEGs, etc)
6. Have access to create Load Balancer Service Extensions
7. Make sure the following tools are available in your terminal's $PATH (Cloud Shell has these preconfigured)
   • gcloud SDK
   • curl
   • jq

(QuickStart) Setup using CloudShell

Use the following GCP CloudShell tutorial, and follow the instructions in Cloud Shell. Alternatively, follow the instructions below.

Configure Environment

1. Authenticate:
   Ensure your active GCP account is selected

   gcloud auth login

2. Navigate:
   Change to the project directory.

   cd extension-processor-grpc

3. Install grpcurl tool

   ./download-and-install-grpcurl.sh

   Add it to your $PATH

   export PATH="$HOME/.grpcurl/bin:${PATH}"

4. Configure and Source Environment:
   Edit env.sh with your settings.

   Then, source it to apply the settings:

   source ./env.sh

Deploy gRPC backend-service

In this step, let's deploy a sample gRPC service to Cloud Run.

./1-create-grpc-service.sh

Once the deployment is complete, it will print out the hostname for the gRPC service.

Export $CR_HOSTNAME variable that was output by the script.

export CR_HOSTNAME="..."

Then, use the following commands to test it out:

export ID_TOKEN=$(gcloud auth print-identity-token)

grpcurl -H "Authorization: Bearer ${ID_TOKEN}" \
   ${CR_HOSTNAME}:443 \
   helloworld.Greeter.SayHello

You can also try sending a request the CountTo RPC to test response streaming:

grpcurl -H "Authorization: Bearer ${ID_TOKEN}" \
        -d '{"to":5}' \
        ${CR_HOSTNAME}:443 helloworld.Greeter.CountTo

Create External Global Load Balancer

In this step, we will disable direct external access to the gRPC service, and instead expose it through a Load Balancer.

This will allow us to later apply Apigee API Management policies to this gRPC service (through a Service Extension).

The initial architecture will look like this:

So, let's create a new GCP External Global Load Balancer that uses a Serverless Network Endpoint Group (NEG) pointing to the gRPC service.

1. Run the script:

   ./2-create-load-balancer.sh

   This script outputs the load balancer's hostname.
   

   Export $LB_HOSTNAME variable that was output by the script.

   export LB_HOSTNAME="..."

   
   ⏳ **Deployment takes about 15 minutes** (due to external certificate provisioning).
   

2. Test the gRPC service through the balancer:

   Now, we are going to test the gRPC service again, but through the Load Balancer URL.
   

   Execute the following grpcurl commands:

   export ID_TOKEN=$(gcloud auth print-identity-token)

   grpcurl -H "Authorization: Bearer ${ID_TOKEN}" \
       ${LB_HOSTNAME}:443 \
       helloworld.Greeter.SayHello

   ✅ You should see a success response.

   ⚠️ If you get a TLS error, wait 15 minutes and retry.

   ℹ️ Notice that you still needed to pass an Authorization header with an ID token. This is because Global Load Balancer is simply passing through the calls to Cloud Run. That's fine for now. Later, once we add Apigee into the mix, the API Proxy itself will inject the Authorization header.

Create Apigee Resources

Next, let's set up your Apigee Environment, API Proxy, and API Product by running the following scripts.

1. Create and Attach Environment:
   Run the script to create an Apigee Environment (with the extension processor enabled) and attach it to a runtime instance:

   ./3-create-environment.sh

   Notice that the new environment has a special property apigee-service-extension-enabled set.

   This tells the Apigee runtime that this is a special environment meant for use with Service Extensions.

2. Create and Deploy API Proxy:
   Run the script to create an API proxy named extproc-proxy and deploy it to the new environment:

   ./4-create-api-proxy.sh

   The API Proxy includes a Verify API Key policy. This means API calls will require a valid API Key.
   
   The API Proxy also contains a policy that mints a Google Cloud Identity Token and injects the "Authorization" header for Cloud Run to use.

3. Create API Product:
   Run the script to create an API Product named extproc-product that includes the extproc-proxy API Proxy:

   ./5-create-api-product.sh

Important: API traffic is not yet routed through Apigee. You will configure this routing in the next step.

Create Service Extension

Next, let's modify the External Global Load Balancer by adding a Service Extension to route traffic through the Apigee runtime.

The new architecture will look like this:

1. Add Service Extension:
   Run the script:

   ./6-create-service-extension.sh

   Once the Service Extension is applied to the Load Balancer, it takes about a minute to take effect.

2. Test the Updated Load Balancer:
   Run the grpcurl command:

   grpcurl ${LB_HOSTNAME}:443 helloworld.Greeter.SayHello

   You should see the request denied due to API Key validation fault.
   

   ✅ This confirms traffic is now routed through the Apigee runtime, and the VA-VerifyAPIKey policy in the extproc-proxy API Proxy is triggering the fault.

In the next step, you will obtain an API Key and retry this request.

Create Developer App

Finally, let's create an Apigee Developer App, extproc-app, and subscribe it to the extproc-product API Product.
Typically, API consumers create apps via a Developer Portal.
For this tutorial, instead, you'll create the app directly using the Apigee CLI.

1. Create the Developer App:
   Run the following script:

   ./7-create-developer-app.sh

   The script will output the API Key for the new app.
   

   Export the $DEVELOPER_APP_KEY variable that was output by the script:

   export DEVELOPER_APP_KEY="..."

2. Test the Service with the API Key:

   Run the following command to send the request:

   grpcurl -H "apikey: ${DEVELOPER_APP_API_KEY}" \
       ${LB_HOSTNAME}:443 helloworld.Greeter.SayHello

   You can also try sending a request the CountTo RPC to test response streaming:

   grpcurl -H "apikey: ${DEVELOPER_APP_API_KEY}" \
           -d '{"to":5}' \
           ${LB_HOSTNAME}:443 helloworld.Greeter.CountTo

🎉 If you see a success response, congrats, you've completed this tutorial!

Conclusion & Cleanup

Congratulations! You've successfully created a Google Cloud External Load Balancer and configured it to use the Apigee Extension Processor.

To clean up the artifacts created, source your env.sh script

source ./env.sh

Then, run the following scripts to clean up the resources created earlier.

./clean-service-extension.sh

./clean-developer-app.sh

./clean-api-product.sh

./clean-api-proxy.sh

./clean-environment.sh

./clean-load-balancer.sh

./clean-grpc-service.sh