This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

This page describes how to configure the Apigee Extension Processor to enable API policy enforcement for API traffic using a Service Extensions-enabled load balancer.

To learn more about the suggested use cases and benefits of using the Apigee Extension Processor for API management, seeApigee Extension Processor overview.

The Apigee Extension Processor is a traffic extension (a type of Service Extension) that lets you use Cloud Load Balancing to send callouts from the data processing path of the application load balancer to the Apigee Extension Processor. Once the load balancer and traffic extension are configured, API traffic is processed by the load balancer. The policies in the Apigee Extension Processor are applied to API traffic using the traffic extension callouts.

The following sections guide you through the steps required to configure the key elements of the Apigee Extension Processor:

Before you begin

Before you begin setting up the Apigee Extension Processor, make sure to complete the following tasks:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, and Network Services APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, and Network Services APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

1. Install theGoogle Cloud CLI.

   After the Google Cloud CLI is installed, run thegcloud components update command to get the latest gcloud components.

2. Provision anApigee instance using version1-15-0-apigee-2 or later, if you have not already done so.

   You can view instance versions in theInstance details page of the Apigee UI in Google Cloud console. Go to theInstances page in the Google Cloud console to select an instance and view its details:

   Go to Instances

   You can use Extension Processor with aSubscription orPay-as-you-go Apigee organization. If you are unsure whether you are using a Subscription or Pay-as-you-go Apigee organization, contact your Apigee organization administrator. For more details about provisioning paid Apigee instances, seeBefore you begin.

3. Confirm that you have a VPC and subnet enabled in the Apigee instance you plan to use. Go to to theVPC Networks page in the Google Cloud console:

   Go to VPC Networks

Required roles

To get the permissions that you need to install the Apigee Extension Processor, ask your administrator to grant you the following IAM roles on the organization:

• Create and manage service accounts:Service Account Admin (roles/iam.serviceAccountAdmin)
• Create and manage service extensions:Service Extensions Admin (roles/networkservices.serviceExtensionsAdmin)
• Create and manage network endpoint groups (NEGs):Compute Instance Admin (roles/compute.instanceAdmin)
• Create and manage networking resources:Compute Network Admin (roles/compute.networkAdmin)
• Create and manage backend services:Compute Load Balancer Admin (roles/compute.loadBalancerAdmin)
• Create and manage Apigee resources:Apigee Org Admin (roles/apigee.admin)

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Set environment variables

In the Google Cloud project that contains your Apigee instance, use the following command to set environment variables:

exportPROJECT_ID=PROJECT_IDexportORG_NAME=$PROJECT_IDexportREGION=REGIONexportINSTANCE=INSTANCEexportVPC_NETWORK_NAME=VPC_NETWORK_NAMEexportSUBNET=SUBNET

Where:

• PROJECT_ID is the ID of the project with your Apigee instance.
• REGION is the Google Cloud region of your Apigee instance.
• INSTANCE is the name of your Apigee instance.
• VPC_NETWORK_NAME is the name of the VPC network in your Google Cloud project that you want to use for the Apigee Extension Processor.
• SUBNET is the name of the subnet in your Google Cloud project that you want to use for the Apigee Extension Processor.

To confirm that the environment variables are set correctly, run the following command and review the output:

echo$PROJECT_ID$ORG_NAME$REGION$INSTANCE$VPC_NETWORK_NAME$SUBNET

Configure an authentication token

To configure an authentication token, run the following command:

exportTOKEN=$(gcloudauthprint-access-token)echo$TOKEN

Configure a load balancer for a backend service

The following sections describe the steps required to set up a global external Application Load Balancer for a backend service, usinghttpbin.org as an example:

1. Create a global external Application Load Balancer.
2. Create a network endpoint group (NEG).
3. Create a backend service.
4. Create a URL map.
5. Create a target proxy.
6. Create a global forwarding rule.

Create a global external Application Load Balancer

To create the load balancer:

1. Set yourgcloud configuration to use your current project:

   gcloudconfigsetprojectPROJECT_ID

   WherePROJECT_ID is the ID of the project with your Apigee instance.

2. Create a global static IP address:

   gcloudcomputeaddressescreateIP_ADDRESS--ip-version=IPV4--global

   WhereIP_ADDRESS is the name of the IP address you want to create. The name must match the regular expression(?:a-z?).

3. Get the IP address and save it as an environment variable:

   IP=$(gcloudcomputeaddressesdescribeIP_ADDRESS--format="get(address)"--global)

   WhereIP_ADDRESS is the name of the IP address you created in the previous step.

4. Create a TLS certificate fornip.io, a third-party service that provides wildcard DNS records for IP addresses:

   gcloud compute ssl-certificates createSSL_CERT_NAME \  --domains="nip.io"

   WhereSSL_CERT_NAME is the name of the certificate you want to create.

Create a network endpoint group (NEG)

To create the network endpoint group (NEG) for your load balancer:

1. Create a NEG:

   gcloudcomputenetwork-endpoint-groupscreateNEG_NAME\--network-endpoint-type=INTERNET_FQDN_PORT\--default-port=443\--global

   WhereNEG_NAME is the name of the NEG you want to create.

2. Add the endpoint forhttpbin.org to the NEG:

   gcloudcomputenetwork-endpoint-groupsupdateNEG_NAME\--add-endpoint=fqdn=httpbin.org,port=443\--global

   WhereNEG_NAME is the name of the NEG you created in the previous step.

Create a backend service

To create the backend service exposed by the load balancer:

1. Create the backend service:

   gcloudcomputebackend-servicescreateBACKEND_SERVICE_NAME\--load-balancing-scheme=EXTERNAL_MANAGED\--protocol=HTTPS\--global

   WhereBACKEND_SERVICE_NAME is the name of the backend service you want to create.

2. Add the NEG to the backend:

   gcloudcomputebackend-servicesadd-backendBACKEND_SERVICE_NAME\--network-endpoint-group=NEG_NAME\--global-network-endpoint-group\--global

   Where:

   • BACKEND_SERVICE_NAME is the name of the backend service you created in the previous step.
   • NEG_NAME is the name of the NEG you created in a previous step.

Create a URL map

To create a URL map between the load balancer and the backend service, use the following command:

gcloudcomputeurl-mapscreateURL_MAP_NAME\--default-serviceBACKEND_SERVICE_NAME\--global

Where:

• URL_MAP_NAME is the name of the URL map you want to create.
• BACKEND_SERVICE_NAME is the name of the backend service you created in a previous step.

Create a target proxy

To create a target proxy for the load balancer, use the following command:

gcloudcomputetarget-https-proxiescreateTARGET_PROXY_NAME\--global\--ssl-certificatesSSL_CERT_NAME\--global-ssl-certificates\--url-mapURL_MAP_NAME\--global-url-map

Where:

• TARGET_PROXY_NAME is the name of the target proxy you want to create.
• URL_MAP_NAME is the name of the URL map you created in a previous step.
• SSL_CERT_NAME is the name of the SSL certificate you created fornip.io in a previous step.

Create a global forwarding rule

To create a global forwarding rule for the load balancer, use the following command:

gcloudcomputeforwarding-rulescreateFORWARDING_RULE_NAME\--load-balancing-scheme=EXTERNAL_MANAGED\--network-tier=PREMIUM\--address=IP_ADDRESS\--target-https-proxy=TARGET_PROXY_NAME\--ports=443\--global

Where:

• FORWARDING_RULE_NAME is the name of the forwarding rule you want to create.
• IP_ADDRESS is the name of the IP address of the NEG endpoint you created in a previous step.
• TARGET_PROXY_NAME is the name of the target proxy you created in a previous step.

Configure the Apigee Extension Processor

The following sections describe the steps required to set up the Apigee Extension Processor:

1. Create an Apigee environment.
2. Create the Extension Processor proxy.

Create an Apigee environment

1. Create an Apigee environment using the following command:

   curl-i-XPOST-H"Authorization: Bearer$TOKEN"\"https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments"-H"Content-Type:application/json"-d\'{        "name": "ENV_NAME",        "displayName": "ENV_NAME",        "state": "ACTIVE",        "deploymentType": "PROXY",        "apiProxyType": "PROGRAMMABLE",        "type": "COMPREHENSIVE",        "properties":        {"property": [            {            "name": "apigee-service-extension-enabled",            "value": "true"            }          ]        }    }'

   WhereENV_NAME is the name of the environment you are creating. The name must contain between 2 and 32 characters which can be lower-case letters, numbers, or hyphens. The name must begin with a letter and cannot end with a hyphen. The name must be different from any other environment name in your organization.

   Confirm that the environment is created:

   curl-i-H"Authorization: Bearer$TOKEN"\"https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments"

   The list of environments should include the environment you just created.

2. Attach the newly created environment to your Apigee instance:

   curl-i-XPOST-H"Authorization: Bearer$TOKEN"\"https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances/$INSTANCE/attachments"-H"Content-Type:application/json"-d\'{        "environment": "ENV_NAME"        }'

   WhereENV_NAME is the name of the environment you created in the previous step.

   This operation may take up to 10 minutes.

3. Create the Apigee environment group:

   curl-H"Authorization: Bearer$TOKEN"-XPOST\"https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups"-H"Content-Type:application/json"-d\'{        "name": "ENV_GROUP_NAME",        "hostnames": ["ENV_GROUP_HOSTNAME"]        }'

   Where:

   • ENV_GROUP_NAME is the name of the environment group you are creating.
   • ENV_GROUP_HOSTNAME is the hostname of the environment group you are creating. The hostname must be a fully qualified domain name (FQDN).Note: The hostname does not need to be resolvable.
4. Attach the new environment to the new environment group:

   curl-H"Authorization: Bearer$TOKEN"-XPOST\"https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups/ENV_GROUP_NAME/attachments"-H"content-type:application/json"-d\'{            "name": "ENV_GROUP_NAME",            "environment": "ENV_NAME"        }'

   Where:

   • ENV_GROUP_NAME is the name of the environment group you are creating.
   • ENV_NAME is the name of the environment you created in an earlier step.

Create the Extension Processor proxy

The Extension Processor proxy is an Apigee API proxy that is used to apply API management policies to the load balancer traffic. You can create ano-target proxyor anServer-Sent event (SSE)-enabled proxy. To learn more about using SSE with Apigee, seeServer-sent events.

To create an Apigee API proxy for use with the Extension Processor load balancer:

Configure the traffic extension

This section describes how to configure the traffic service extension for your Extension Processor, using the following steps:

1. Create an Apigee Private Service Connect Network Endpoint Group.
2. Create a load balancer service extension.
3. Send a request to the load balancer.

Create an Apigee Private Service Connect Network Endpoint Group

In this section, you will create an Apigee Private Service Connect (PSC) Network Endpoint Group (NEG) that is used to connect to your Apigee instance. To learn more about PSC, seeSouthbound networking patterns.

curl-XPOST"https://networkservices.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/global/lbTrafficExtensions?lbTrafficExtensionId=global-xlb-httpbin-apim-policy"\-H"Authorization: Bearer$TOKEN"\-H"Content-Type: application/json"\-d'{    "name": "global-xlb-httpbin-apim-policy",    "forwardingRules": [        "https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME"    ],    "extensionChains": [        {            "name": "httpbin-apigee-extension-chain",            "matchCondition": {                "celExpression": "true"            },            "extensions": [                {                    "name": "httpbin-apigee-extension",                    "authority": "ENV_GROUP_HOSTNAME",                    "service": "https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/backendServices/PSC_NEG_BACKEND_SERVICE",                    "supportedEvents": [                        "REQUEST_HEADERS",                        "REQUEST_BODY",                        "REQUEST_TRAILERS",                        "RESPONSE_HEADERS",                        "RESPONSE_BODY",                        "RESPONSE_TRAILERS"                    ],                    "timeout": "1s",                    "requestBodySendMode": "BODY_SEND_MODE_FULL_DUPLEX_STREAMED",                    "responseBodySendMode": "BODY_SEND_MODE_FULL_DUPLEX_STREAMED"                }            ]        }    ],    "loadBalancingScheme": "EXTERNAL_MANAGED",    "metadata": {        "apigee-extension-processor": "EXT_PROC_NAME",        "apigee-request-body": "true",        "apigee-response-body": "true"    }}'

curl"https://networkservices.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/global/lbTrafficExtensions/httpbin-apigee-extension"\-H"Authorization: Bearer$TOKEN"\-H"Content-Type: application/json"

createTime:'2025-03-22T00:29:16.056719825Z'extensionChains:-extensions:-authority:extension-processor-test.hybrid.e2e.apigeeks.netname:httpbin-apigee-extensionservice:https://www.googleapis.com/compute/v1/projects/123456789012/global/backendServices/ep-test-psc-neg-bessupportedEvents:-REQUEST_HEADERS-REQUEST_BODY-REQUEST_TRAILERS-RESPONSE_HEADERS-RESPONSE_BODY-RESPONSE_TRAILERStimeout:1smatchCondition:celExpression:'true'name:httpbin-apigee-extension-chainforwardingRules:-https://www.googleapis.com/compute/v1/projects/123456789012/global/forwardingRules/ep-test-fw-ruleloadBalancingScheme:EXTERNAL_MANAGEDmetadata:apigee-extension-processor:ep-test-proxyapigee-request-body:trueapigee-response-body:truename:projects/extension-processor-test/locations/global/lbTrafficExtensions/global-xlb-httpbin-apim-policyupdateTime:'2025-03-22T00:29:31.183275055Z'

curl"https://LB_DOMAIN_NAME/get"

{"status":200,{"args":{},"headers":{...},"origin":"173.93.50.108","url":"https://httpbin.org/get"}}

In this example, aVerifyAPIkey andAssignMessage policy are configured for the Extension Processor. These policies are used to validate API keys included in requests to Apigee and inject a Google token into request headers for calls to a backend service. This scenario would be useful for API providers using the Apigee Extension Processor to authorize and authenticate requests to their Apigee services and seamlessly inject theGoogle auth tokens required for a backend service like Vertex AI.

Add the VerifyAPIKey policy for API key validation

The following sections describe how to use the VerifyAPIKey policy to validate API keys for calls to your backend service using the Extension Processor:

1. Attach the VerifyAPIKey policy to the Extension Processor.
2. Create an API product.
3. Create a developer App and App credentials.
4. Send a request to the load balancer using the API key.

Attach the VerifyAPIKey policy to the proxy

To attach a VerifyAPIKey policy to the Extension Processor proxy:

1. In the Google Cloud console, go to theProxy Development> API Proxies page.

   Go to API Proxies

2. Select the Extension Processor proxy you created inCreate an extension processor section.
3. Click theDevelop tab.
4. In the navigation pane, clickadd_circle in thePolicies section.
5. In theCreate policy dialog, selectVerifyAPIKey from the list of policies.
6. In theVerifyAPIKey pane, complete the required fields in theName andDisplay name sections using the following values:
   • Name: Enter a policy name. For example,VA-verify-api-key.
   • Display name: Enter policy name for use in the UI. For example,VA-verify-api-key.
7. ClickCreate.

   The XML specification for the VerifyAPIKey policy included in the Extension Processor proxy should appear similar to the following:

   <?xmlversion="1.0"encoding="UTF-8"standalone="yes"?><VerifyAPIKeycontinueOnError="false"enabled="true"name="VA-verify-api-key"><DisplayName>VA-verify-api-key</DisplayName><Properties/><APIKeyref="request.queryparam.x-api-key"/></VerifyAPIKey>

8. Deploy the new proxy revision.

Create an API product

To create an API product and configure the API operation set for your service:

1. Follow the steps inCreating an API product to create an API product for your service. You can configure theProduct details for the API product however you wish.
2. Follow the steps inOperations to add an API operation set to the API product, according to the following specifications:
   • Source:

     In the Google Cloud console, go to theDistribution> API Products page.

     Go to API Products

     Select the API product you created in an earlier step.
   • Operation: ClickEdit and configure the following paths and methods:
     • Path:/get with Method:GET
     • Path:/PROXY_NAME with Method:GET

       PROXY_NAME is the name of the proxy you created in an earlier step.

Create a developer App and App credentials

To create a developer App and App credentials for the newly created API product:

1. Go to to theApigee API management page in the Google Cloud console:

   Apigee API management

2. Create a developer:
   1. SelectDistribution> Developers.
   2. On theDevelopers page, click+ Create.
   3. In theAdd developer page, complete the required fields using any values you wish.
   4. ClickAdd.
3. Create an App:
   1. SelectDistribution> Apps.
   2. On theApps page, click+ Create
   3. On theCreate App page, complete the required fields in theApp Details section using the following values:
      • App name: Enter a name for the App. For example,ext-proc-app
      • Developer: Select the developer you created in the previous step, or another developer from the list.
   4. In theApp Credentials section, click+ Add Credential.
   5. In theCredential section, selectNever from theExpiry list box.
   6. In theProducts section, click+ Add products to display theAdd Products pane.
   7. Select the API product you created in the previous step.
   8. ClickOK.
   9. ClickAdd to close theAdd Products pane.
   10. ClickCreate.
4. In theApp Details page, in theCredential section, click visibility_off to display the value of theKey.

   Copy theKey value. You will use this key to make API calls to your service in a later step.

5. In theApp Details page, in theCredential section, clickvisibility_off to display the value of theApp Secret.

Send a request to the load balancer using the API key

To test the API key validation, send a request to the load balancer using the API key:

curl"https://LB_DOMAIN_NAME/get"

WhereLB_DOMAIN_NAME is the domain name you used for the load balancer and SSL certificate.

The response should fail without an API key.

Send another request to the load balancer, using the API key in the request:

curl"https://LB_DOMAIN_NAME/get?key=API_KEY"

Where:

• LB_DOMAIN_NAME is the domain name you used for the load balancer and SSL certificate.
• API_KEY is the API key from the Developer App credentials revealed in an earlier step.

The response should indicate successful authortization for the endpoint. This indicates that the Extension Processor validated the API key and the request can now be processed by the Apigee proxy.

Add the AssignMessage policy for Google authentication

If you want to use your Extension Processor to provide API management for a Google-authenticated service, you can inject a Google access token or Google ID token into requests sent to the backend service using theAssignMessage policy.

The following sections describe how to use the AssignMessage policy to inject a Google authentication token into requests sent to the backend service using the Extension Processor:

1. Attach the AssignMessage policy to the proxy.
2. Send a request to the load balancer to test token injection.

Attach the AssignMessage policy to the proxy

To add the AssignMessage policy to your proxy:

1. In the Google Cloud console, go to theProxy Development> API Proxies page.

   Go to API Proxies

2. Select the Extension Processor proxy you created inCreate an extension processor section.
3. Click theDevelop tab.
4. In the navigation pane, click add_circle in thePolicies section.
5. In theCreate policy dialog, selectAssignMessage from the list of policies.
6. In theAssign Message pane, complete the required fields in theName andDisplay name sections using the following values:
   • Name: Enter a policy name. For example,AM-auth.
   • Display name: Enter a policy name to display in the UI. For example,AM-auth.
7. ClickCreate.
8. Under the<Set> element, add the following child elements:

   <Set><Authentication><HeaderName>Authorization</HeaderName><GoogleAccessToken><Scopes><Scope>https://www.googleapis.com/auth/cloud-platform</Scope></Scopes></GoogleAccessToken></Authentication></Set>

9. ClickSave.
10. Deploy the new revision using a Google service account.

The service account is used to generate Google access tokens and inject them into the request header for API calls to Google backend services.

Send a request to the load balancer to test token injection

To confirm that token injection is working, send a request to the load balancer:

curl"https://LB_DOMAIN_NAME/get"

WhereLB_DOMAIN_NAME is the domain name you used for the load balancer and SSL certificate.

The response should appear similar to the following:

{..."headers":{"Accept":"*/*","Authorization":"Bearer ya29.c.c0ASRK0Gbw03y9cfvxL11DxaRYBQUU18SmUP4Vu63OckHI5cX7wJ4DmGMG2vbDDS69HXJHqMj-lak4tcqOsJGmE65crn2gNuJLanXidwM8","First":"1.0","Host":"apigee-ext-proc-test.apigee.net","Second":"1.0","Sum":"2","User-Agent":"curl/8.7.1","X-Api-Key":"McYcHGR3PTSGLXExvKADwQ1JJeCjgPDUvAakCl0rJKCFaX0Y","X-Cloud-Trace-Context":"0fd3dadc2a3c328fa968d5f5f1434c29/18300783092696918345"},...}

The response should show the successful injection of the Google authentication token into the request header.

With the successful application of the AssignMessage policy, the client's successful request (containing the API key) to Apigee in the example scenario is modified further to include a Google authentication token in the request header, as required by the Google-authenticated backend service.