This page applies to Apigee and Apigee 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, see Apigee 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.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Apigee, Compute Engine, and Network Services APIs.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Apigee, Compute Engine, and Network Services APIs.
Install the Google Cloud CLI.
After the Google Cloud CLI is installed, run the
gcloud components update
command to get the latest gcloud components.Provision an Apigee instance using version
1-15-0-apigee-2
or later, if you have not already done so.You can view instance versions in the Instance details page of the Apigee UI in Google Cloud console. Go to the Instances page in the Google Cloud console to select an instance and view its details:
You can use Extension Processor with a Subscription or Pay-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, see Before you begin.
- Confirm that you have a VPC and subnet enabled in the Apigee instance you plan to use. Go to to the VPC Networks page in the Google Cloud console:
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, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Set environment variables
In the Google Cloud project that contains your Apigee instance, use the following command to set environment variables:
export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=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:
export TOKEN=$(gcloud auth print-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, using httpbin.org as an example:
- Create a global external Application Load Balancer.
- Create a network endpoint group (NEG).
- Create a backend service.
- Create a URL map.
- Create a target proxy.
- Create a global forwarding rule.
Create a global external Application Load Balancer
To create the load balancer:
- Set your
gcloud
configuration to use your current project:gcloud config set project PROJECT_ID
Where PROJECT_ID is the ID of the project with your Apigee instance.
- Create a global static IP address:
gcloud compute addresses create IP_ADDRESS --ip-version=IPV4 --global
Where IP_ADDRESS is the name of the IP address you want to create. The name must match the regular expression
(?:a-z?)
. - Get the IP address and save it as an environment variable:
IP=$(gcloud compute addresses describe IP_ADDRESS --format="get(address)" --global)
Where IP_ADDRESS is the name of the IP address you created in the previous step.
- Create a TLS certificate for
nip.io
, a third-party service that provides wildcard DNS records for IP addresses:gcloud compute ssl-certificates create SSL_CERT_NAME \ --domains="nip.io"
Where SSL_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:
- Create a NEG:
gcloud compute network-endpoint-groups create NEG_NAME \ --network-endpoint-type=INTERNET_FQDN_PORT \ --default-port=443 \ --global
Where NEG_NAME is the name of the NEG you want to create.
- Add the endpoint for httpbin.org to the NEG:
gcloud compute network-endpoint-groups update NEG_NAME \ --add-endpoint=fqdn=httpbin.org,port=443 \ --global
Where NEG_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:
- Create the backend service:
gcloud compute backend-services create BACKEND_SERVICE_NAME \ --load-balancing-scheme=EXTERNAL_MANAGED \ --protocol=HTTPS \ --global
Where BACKEND_SERVICE_NAME is the name of the backend service you want to create.
- Add the NEG to the backend:
gcloud compute backend-services add-backend BACKEND_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:
gcloud compute url-maps create URL_MAP_NAME \ --default-service BACKEND_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:
gcloud compute target-https-proxies create TARGET_PROXY_NAME \ --global \ --ssl-certificates SSL_CERT_NAME \ --global-ssl-certificates \ --url-map URL_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 for
nip.io
in a previous step.
Create a global forwarding rule
To create a global forwarding rule for the load balancer, use the following command:
gcloud compute forwarding-rules create FORWARDING_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:
Create an Apigee environment
- Create an Apigee environment using the following command:
curl -i -X POST -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" } ] } }'
Where ENV_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.
- Attach the newly created environment to your Apigee instance:
curl -i -X POST -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances/$INSTANCE/attachments" -H "Content-Type:application/json" -d \ '{ "environment": "ENV_NAME" }'
Where ENV_NAME is the name of the environment you created in the previous step.
This operation may take up to 10 minutes.
- Create the Apigee environment group:
curl -H "Authorization: Bearer $TOKEN" -X POST \ "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).
- Attach the new environment to the new environment group:
curl -H "Authorization: Bearer $TOKEN" -X POST\ "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
To create an Apigee no-target API proxy for use with the Extension Processor load balancer:
- Follow the steps in Creating an API proxy to create
a No target proxy with the following specifications:
- Proxy template: Select No target.
- Proxy name: Enter a proxy name.
- Base path: Set any base path you would like. The path will not be used.
The XML specification for the proxy should appear similar to the following:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <APIProxy revision="1" name="extproc-sample"> <DisplayName/> <Description/> <CreatedAt>1739581781912</CreatedAt> <LastModifiedAt>1739582447868</LastModifiedAt> <BasePaths>/</BasePaths> <Policies></Policies> <ProxyEndpoints> <ProxyEndpoint>default</ProxyEndpoint> </ProxyEndpoints> </APIProxy>
- Follow the steps in Deploy an API proxy to deploy the proxy to the environment you created earlier.
Configure the traffic extension
This section describes how to configure the traffic service extension for your Extension Processor, using the following steps:
- Create an Apigee Private Service Connect Network Endpoint Group.
- Create a load balancer service extension.
- 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, see Southbound networking patterns.
To create an Apigee PSC NEG:
- Get the Apigee PSC service attachment:
PSC_ATTACHMENT=$(curl -s -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances" \ | jq -r '.instances[] | select(.name = "'$INSTANCE'") | .serviceAttachment' \ )
To view the service attachment:
echo $PSC_ATTACHMENT
The response should appear similar to the following:
projects/apigee-psc-autopush/regions/us-west1/serviceAttachments/apigee-us-west1-1234567890-psc-service-attachment
- Create the PSC NEG in the same region as your Apigee instance:
gcloud compute network-endpoint-groups create apigee-neg-$REGION \ --network-endpoint-type=private-service-connect \ --psc-target-service=$PSC_ATTACHMENT \ --region=$REGION \ --network=$VPC_NETWORK_NAME \ --subnet=$SUBNET
The response should appear similar to the following:
projects/ab123456cd78ef910g-tp/regions/asia-northeast1/serviceAttachments/apigee-asia-northeast1-abcd
- Create an
HTTP/2
backend service pointing to the PSC NEG, if one doesn't already exist:gcloud compute backend-services create PSC_NEG_BACKEND_SERVICE \ --load-balancing-scheme=EXTERNAL_MANAGED \ --protocol=HTTP2 \ --global
Where PSC_NEG_BACKEND_SERVICE is the name of the backend service you want to create.
- Add the PSC NEG backend service:
gcloud compute backend-services add-backend PSC_NEG_BACKEND_SERVICE \ --network-endpoint-group=apigee-neg-$REGION \ --network-endpoint-group-region=$REGION \ --global
Where PSC_NEG_BACKEND_SERVICE is the name of the backend service you created in a previous step.
- Enable logging for the backend service:
gcloud compute backend-services update PSC_NEG_BACKEND_SERVICE \ --global \ --enable-logging \ --logging-sample-rate=1.0
Where PSC_NEG_BACKEND_SERVICE is the name of the backend service you created in a previous step.
Create a load balancer service extension
To create a load balancer service extension:
- Create a new file named
global-xlb-httpbin-apim-policy.yaml
with the following contents:# global-xlb-httpbin-apim-policy.yaml name: global-xlb-httpbin-apim-policy metadata: apigee-extension-processor: EXT_PROC_NAME # Must match the name of the API proxy created in an earlier step. forwardingRules: - https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME loadBalancingScheme: EXTERNAL_MANAGED extensionChains: - name: "httpbin-apigee-extension-chain" matchCondition: celExpression: 'true' extensions: - name: 'httpbin-apigee-extension' authority: ENV_GROUP_HOSTNAME # The domain name used for the environment group. service: https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/backendServices/PSC_NEG_BACKEND_SERVICE failOpen: false timeout: 1s supportedEvents: - REQUEST_HEADERS - RESPONSE_HEADERS
Where:
- EXT_PROC_NAME This name must match the name of the API proxy you created in an earlier step.
- FORWARDING_RULE_NAME is the name of the forwarding rule you created in an earlier step.
- ENV_GROUP_HOSTNAME is the domain name used for the environment group.
- PSC_NEG_BACKEND_SERVICE is the name of the backend service you created in an earlier step.
- Apply the service extension to the load balancer forwarding rule:
gcloud service-extensions lb-traffic-extensions import global-xlb-httpbin-apim-policy \ --source=global-xlb-httpbin-apim-policy.yaml \ --location=global
This operation may take a few minutes. To check the status of the operation, use the following command:
gcloud service-extensions lb-traffic-extensions describe global-xlb-httpbin-apim-policy --location global
The response should appear similar to the following and display the forwarding rule and backend service:
createTime: '2025-03-22T00:29:16.056719825Z' extensionChains: - extensions: - authority: extension-processor-test.hybrid.e2e.apigeeks.net name: httpbin-apigee-extension service: https://www.googleapis.com/compute/v1/projects/123456789012/global/backendServices/ep-test-psc-neg-bes supportedEvents: - REQUEST_HEADERS - RESPONSE_HEADERS timeout: 1s matchCondition: celExpression: 'true' name: httpbin-apigee-extension-chain forwardingRules: - https://www.googleapis.com/compute/v1/projects/123456789012/global/forwardingRules/ep-test-fw-rule loadBalancingScheme: EXTERNAL_MANAGED metadata: apigee-extension-processor: ep-test-proxy name: projects/extension-processor-test/locations/global/lbTrafficExtensions/global-xlb-httpbin-apim-policy updateTime: '2025-03-22T00:29:31.183275055Z'
Send a request to the load balancer
To test the load balancer and Extension Processor setup, send a request to the load balancer:
curl "https://LB_DOMAIN_NAME/get"
Where LB_DOMAIN_NAME is the domain name you used for the load balancer and SSL certificate. If you
used nip.io
, the domain name will look similar to IP_ADDRESS.nip.io
.
The response should appear similar to the following:
{"status": 200, { "args": {}, "headers": { ... }, "origin": "173.93.50.108", "url": "https://httpbin.org/get" } }
Use policies with the Extension Processor
This section describes how to use policies with the Extension Processor.
In this example, a VerifyAPIkey and AssignMessage 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 the Google 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:
- Attach the VerifyAPIKey policy to the Extension Processor.
- Create an API product.
- Create a developer App and App credentials.
- 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:
- In the Apigee UI in Cloud console, go to the Develop tab and select the Extension Processor proxy you created in an earlier step.
- In the Policies section, click + Add policy.
- In the Add policy pane, select VerifyAPIKey from the list of policies.
- In the VerifyAPIKey pane, complete the required fields in the Policy name and Display name sections using the following values:
- Policy 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
.
- Policy name: Enter a policy name. For example,
- Click Create.
The XML specification for the VerifyAPIKey policy included in the Extension Processor proxy should appear similar to the following:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <VerifyAPIKey continueOnError="false" enabled="true" name="VA-verify-api-key"> <DisplayName>VA-verify-api-key</DisplayName> <Properties/> <APIKey ref="request.queryparam.x-api-key"/> </VerifyAPIKey>
- Deploy the new proxy revision.
Create an API product
To create an API product and configure the API operation set for your service:
- Follow the steps in Creating an API product to create an API product for your service. You can configure the Product details for the API product however you wish.
- Follow the steps in Operations to add an API operation set to the API product, according to the
following specifications:
- Source: Choose API Proxy and select the proxy you created in an earlier step.
- Operation: 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.
- Path:
Create a developer App and App credentials
To create a developer App and App credentials for the newly created API product:
Go to to the Apigee API management page in the Google Cloud console:
- Create a developer:
- Select Distribution > Developers.
- On the Developers page, click + Create.
- In the Add developer page, complete the required fields using any values you wish.
- Click Add.
- Create an App:
- Select Distribution> Apps.
- On the Apps page, click + Create
- On the Create App page, complete the required fields in the App 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.
- App name: Enter a name for the App. For example,
- In the App Credentials section, click + Add Credential.
- In the Credential section, select Never from the Expiry list box.
- In the Products section, click + Add products to display the Add Products pane.
- Select the API product you created in the previous step.
- Click OK.
- Click Add to close the Add Products pane.
- Click Create.
- In the App Details page, in the Credential section, click
visibility_off to display the value of the Key.
Copy the
Key
value. You will use this key to make API calls to your service in a later step. - In the App Details page, in the Credential section, click visibility_off to display the value of the App 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"
Where LB_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 the AssignMessage 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:
- Attach the AssignMessage policy to the proxy.
- 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:
- In the Apigee UI in Cloud console, go to the Develop tab and select the proxy you created in an earlier step.
- In the Policies section, click + Add policy.
- In the Add policy pane, select Assign Message from the list of policies.
- In the Assign Message pane, complete the required fields in the Policy name and Display name sections using the following values:
- Policy name: Enter a policy name. For example,
AM-auth
. - Display name: Enter a policy name to display in the UI. For example,
AM-auth
.
- Policy name: Enter a policy name. For example,
- Click Create.
- 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>
- Click Save.
- 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"
Where LB_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.