This page applies to Apigee and Apigee hybrid.
View
Apigee Edge documentation.
This page shows you how to define an API proxy as an Apigee Feature Template in YAML and deploy it with the Google Cloud CLI. You first build a simple proxy, and then build a more complete example that fronts a Gemini model.
For background, see Configuring a proxy with YAML. For the full schema, see API proxy YAML configuration reference.
Before you begin
For Part 2 only: enable the Agent Platform API in the Google Cloud project that hosts the model:
gcloud services enable aiplatform.googleapis.com \ --project=PROJECT_IDReplace PROJECT_ID with the ID of the project that hosts the model, for example
my-apigee-project. This walkthrough uses the project of your Apigee organization. Part 1 doesn't need this API. You don't need to choose a region, because the template uses the global endpoint. It can take a short time for the API to become active after you enable it.- Install and initialize the Google Cloud CLI.
- Have an Apigee organization and at least one environment. Note the organization and environment names; the examples use ORG and ENV as placeholders (see Placeholders used on this page). The AI gateway in Part 2 additionally requires an Intermediate or Comprehensive environment (not a Base environment); see Apigee environment types.
- Make sure you have the required permissions:
- To import (create) an API proxy: the API Admin role
(
roles/apigee.apiAdmin), or an equivalent role that grantsapigee.proxies.create. - To deploy an API proxy: Environment Admin
(
roles/apigee.environmentAdmin) on the target environment, and API Reader (roles/apigee.apiReaderV2) at the project level. - To create the API product, developer, and app that produce the API key
in Part 2, Step 6: API Admin
(
roles/apigee.apiAdmin) and Developer Admin (roles/apigee.developerAdmin). For the full list of roles, see Apigee roles.
- To import (create) an API proxy: the API Admin role
(
Placeholders used on this page
Replace each placeholder in the commands with your own value. Most values already exist and you look them up. You choose SA_NAME yourself, and some values are generated as you work through the steps.
| Placeholder | Source | Description |
|---|---|---|
| ORG | Look up | Your Apigee organization name. This is usually the same as
PROJECT_ID. To list the organizations you can access, run
gcloud apigee organizations list. |
| ENV | Look up | An environment in your organization, for example test.
Part 1, Step 4 shows how to list them. |
| PROJECT_ID | Look up | The ID of the Google Cloud project that holds your Apigee
organization, for example my-apigee-project. To print the
active project, run gcloud config get project. |
| HOSTNAME | Look up | A hostname of an environment group that contains ENV, for
example api.example.com. Part 1, Step 5
shows where to find it. |
| SA_NAME | You choose | A name for the service account that you create in
Part 2, Step 3, for example
apigee-ai-gateway. |
| PROJECT_NUMBER | Look up | The project number of PROJECT_ID, for example
123456789012.
Part 2, Step 3 shows the command that
prints it. |
| REGION | You choose | Optional. A region that serves your model, for example
us-central1. You need it only if you switch the
gemini-target feature to a regional endpoint. |
| REVISION | Generated | The proxy revision number that the import command prints in
Part 2, Step 4, for example 1. |
| API_KEY | Generated | The API key that Apigee generates when you register a developer app in Part 2, Step 6. |
Part 1: Create a simple API proxy
In this section, you create a proxy that forwards requests to the Apigee mock target service and enforces a rate limit.
Step 1: Create the template
A template is the file you deploy. It defines your proxy's base path, routes, and backend target, and lists the features to include.
Create a project directory for your templates, with a features
subdirectory for the features they use:
mkdir -p proxy-templates/features cd proxy-templates
When you finish this part, the project directory looks like this:
proxy-templates/ hello-proxy.yaml features/ spike-arrest.yaml
In the proxy-templates directory, create a file named
hello-proxy.yaml:
gateway: apigee schemaVersion: 1.0.0 name: hello-proxy type: template description: A simple proxy to the Apigee mock target, protected by a rate limit. features: - ./features/spike-arrest.yaml endpoints: - name: default basePath: /hello routes: - name: default target: default targets: - name: default url: https://mocktarget.apigee.net
This template defines:
- An endpoint with the base path
/hello. Clients call the proxy at this path. - A route that sends requests to the target named
default. - A target that points to the backend URL.
- A feature,
spike-arrest.yaml, which you create next.
Step 2: Create the feature
A feature is a reusable unit of configuration that holds policies. A template can't contain policies directly, so the rate-limiting policy lives in a feature.
In the features directory, create a file named
spike-arrest.yaml:
gateway: apigee schemaVersion: 1.0.0 name: spike-arrest displayName: Spike Arrest type: feature description: Protects the backend by smoothing traffic spikes. categories: - traffic parameters: - name: RATE displayName: RATE description: Maximum request rate, for example 30ps (per second) or 100pm (per minute). default: 30ps examples: - 30ps - 100pm defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: SA-SpikeArrest policies: - name: SA-SpikeArrest type: SpikeArrest content: SpikeArrest: metadata: name: SA-SpikeArrest enabled: "true" continueOnError: "false" DisplayName: SA-SpikeArrest Rate: "{RATE}"
This feature:
- Defines a SpikeArrest policy that limits the request rate.
- Uses
defaultEndpoint.flowsto add the policy to the request PreFlow, so it runs on every request. - Declares a parameter,
RATE, whose default (30ps) is substituted for{RATE}when the proxy is compiled.
Step 3: Import the proxy
Import the template to create an API proxy revision. Run this command from the
proxy-templates directory, which contains the template:
gcloud apigee apis import hello-proxy \
--from-template=hello-proxy.yaml \
--organization=ORGThe CLI compiles the template and its feature into an API proxy bundle, uploads it, and prints the new proxy revision. Importing creates a revision but does not deploy it.
Step 4: Deploy the proxy
List the environments in your organization:
gcloud apigee environments list --organization=ORG
The command prints the environment names. Pick one to use as ENV, and deploy the revision to it:
gcloud apigee apis deploy \
--api=hello-proxy \
--environment=ENV \
--organization=ORGBy default, this command deploys the latest revision. To deploy a specific
revision, pass its number as the first argument, for example
gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV.
If a different proxy is already deployed at the same base path, add
--override to replace it with zero downtime.
Step 5: Call the proxy
To call the deployed proxy over the network, your environment must be attached to an environment group that has a routable hostname. If you just created your organization, confirm this is set up before you call the proxy; see About environments and environment groups.
Find the hostname of an environment group that contains your environment:
- In the Google Cloud console, go to Apigee > Management > Environments.
- Select the Environment groups tab.
- Find the environment group that contains your environment, and copy a value from its Hostnames column.
Call the proxy at that hostname, using the base path from your template:
curl https://HOSTNAME/hello
Replace HOSTNAME with the hostname you copied. A successful response comes from the mock target service.
Part 2: Build an AI gateway for Gemini
This section builds a more complete proxy: an AI gateway that forwards requests to a Gemini model on Gemini Enterprise Agent Platform, enforces a rate limit, and requires an API key. It uses one template, three features, and a service account.
Unlike the simple proxy in Part 1, this proxy
calls a Google Cloud service (Agent Platform).
The gemini-target feature uses
auth: GoogleAccessToken, so Apigee attaches a Google OAuth
token to each request to Agent Platform. That
token is issued for a service account that you create and then
provide when you deploy the proxy, so this part adds a step to create that
service account (Step 3).
Before you start, make sure that the Agent Platform API is enabled in the project that hosts the model, as described in Before you begin. You don't need to have used Agent Platform before.
In Part 2, PROJECT_ID is the ID of your Apigee
organization's project, for example my-apigee-project. Part 2 uses
this one project throughout: you enable the API in it, create the service
account in it, and set it as the template's MODEL_PROJECT_ID
value.
Step 1: Create the template
In the proxy-templates directory from
Part 1, create a file named
ai-gateway.yaml:
gateway: apigee schemaVersion: 1.0.0 name: ai-gateway type: template description: AI gateway that fronts a Gemini model with throttling and API key enforcement. features: - ./features/spike-arrest.yaml - ./features/verify-api-key.yaml - ./features/gemini-target.yaml parameters: - name: MODEL_PROJECT_ID default: PROJECT_ID - name: MODEL default: gemini-3.8-flash endpoints: - name: gemini basePath: /v1/gemini routes: - name: default target: gemini
The parameters list sets values for the parameters that the
gemini-target feature declares, which you create in the next step.
Replace PROJECT_ID with the project ID that you used to
enable the API, for example
my-apigee-project.
Step 2: Create the features
The template uses three features. Reuse the
spike-arrest.yaml feature from Part 1,
and create the other two in the features directory. When you
finish this step, the project directory looks like this:
proxy-templates/ hello-proxy.yaml ai-gateway.yaml features/ spike-arrest.yaml verify-api-key.yaml gemini-target.yaml
Create features/verify-api-key.yaml to require an API key in the
x-api-key header:
gateway: apigee schemaVersion: 1.0.0 name: verify-api-key displayName: Verify API Key type: feature description: Requires a valid API key in the x-api-key request header. categories: - security defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: VA-VerifyAPIKey policies: - name: VA-VerifyAPIKey type: VerifyAPIKey content: VerifyAPIKey: metadata: name: VA-VerifyAPIKey enabled: "true" continueOnError: "false" DisplayName: VA-VerifyAPIKey APIKey: metadata: ref: request.header.x-api-key
Create features/gemini-target.yaml to route to a Gemini model,
authenticated with a Google access token:
gateway: apigee schemaVersion: 1.0.0 name: gemini-target displayName: Gemini Target type: feature description: Routes requests to a Gemini model on the Gemini Enterprise Agent Platform, authenticated with a Google access token. categories: - llm parameters: - name: MODEL_PROJECT_ID displayName: Model Project ID description: Google Cloud project that hosts the Gemini model. Supplied by the template; no default. - name: MODEL displayName: Model description: The Gemini model to route to. default: gemini-3.8-flash examples: - gemini-3.8-flash - gemini-4-argon targets: - name: gemini url: https://aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/global/publishers/google/models/{MODEL}:generateContent auth: GoogleAccessToken scopes: - https://www.googleapis.com/auth/cloud-platform
The gemini-target feature declares two parameters and
substitutes them into the target URL:
MODEL_PROJECT_ID: the Google Cloud project that hosts the model. It has no default, so the template must set it to your project ID.MODEL: the Gemini model to call. The feature's default isgemini-3.8-flash.
When the CLI compiles the template, it resolves each parameter as follows:
- If the template's
parameterslist has an entry with the same name and a non-emptydefault, the CLI uses that value. - Otherwise, the CLI uses the feature's
default. - If neither sets a value, the CLI replaces
{name}with an empty string. The import doesn't report an error, so a missingMODEL_PROJECT_IDproduces a target URL with no project ID.
There is no command-line flag to set parameter values when you import. To
use a different project or model, edit its value in the template's
parameters list and import the template again.
The gemini-target feature uses
auth: GoogleAccessToken so that Apigee attaches a Google
access token to each request to
Agent Platform.
The URL uses the global endpoint (host
aiplatform.googleapis.com and locations/global), which
serves gemini-3.8-flash and routes requests to available capacity
across regions. With the global endpoint, you don't need to choose a
region.
To call a different model, set MODEL in the template's
parameters list to the model's ID. To list the Gemini models that
you can call, run:
gcloud ai model-garden models list --model-filter=gemini
Each value in the MODEL_ID column looks like
google/gemini-3.8-flash@default. Set MODEL to the part
between google/ and @, such as
gemini-4-argon. The model's card in Model Garden in the
Google Cloud console shows the same ID. To check that a model supports the global
endpoint, see the Global tab in
Google
model endpoint locations.
If you need to control which region processes requests, replace the
url line in features/gemini-target.yaml with the
regional form, which puts the region in both the host and the
path:
url: https://REGION-aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/REGION/publishers/google/models/{MODEL}:generateContent
Replace REGION with a region that serves your model, as listed in the same Google model endpoint locations tables. For when to avoid the global endpoint, see Global endpoint.
Step 3: Create a service account for the proxy
Because the gemini-target feature uses
auth: GoogleAccessToken, the deployed proxy calls
Agent Platform as a service account.
Create that service account, give it access to
Agent Platform, and let the Apigee
service agent use it. You provide this service account when you deploy the
proxy in Step 5. For more detail, see
Using Google
authentication.
- Create a user-managed service account in the same Google Cloud project as
your Apigee organization. (The Compute Engine default service account
is not accepted.) For other ways to create one, see
Creating
and managing service accounts.
gcloud iam service-accounts create SA_NAME \ --project=PROJECT_ID \ --display-name="Apigee AI gateway"Pick a descriptive name for SA_NAME, for example
apigee-ai-gateway. The command creates the service accountSA_NAME@PROJECT_ID.iam.gserviceaccount.com, for exampleapigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com. - Grant the service account access to the backend it calls. For an
Agent Platform target, grant the
Agent Platform User role (
roles/aiplatform.user):gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/aiplatform.user"If your project's IAM policy already contains conditional role bindings, add
--condition=Noneto this command. - Let the Apigee service agent mint tokens for the service account by
granting it the Service Account Token Creator role
(
roles/iam.serviceAccountTokenCreator) on the service account:gcloud iam service-accounts add-iam-policy-binding \ SA_NAME@PROJECT_ID.iam.gserviceaccount.com \ --project=PROJECT_ID \ --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"To find PROJECT_NUMBER, run
gcloud projects describe PROJECT_ID --format='value(projectNumber)'.
Step 4: Import the proxy
Import the template to create an API proxy revision. Run this command from the
proxy-templates directory, which contains the template:
gcloud apigee apis import ai-gateway \
--from-template=ai-gateway.yaml \
--organization=ORGNote the revision number in the command output; you need it in
Step 5. To print just the revision number, add
--format="value(revision)" to the import command.
Step 5: Deploy the proxy with the service account
Deploying the AI gateway differs from the simple proxy in Part 1 in two ways:
- You must provide the service account you created in
Step 3. If you deploy without one, the
deployment fails with a
MISSING_SERVICE_ACCOUNTerror. - You must deploy to an Intermediate or Comprehensive environment.
This proxy uses an extensible policy, which a Base environment does not
support; deploying to one fails with the error
Extensible proxy can not be deployed to a base environment
. Thegcloud apigee environments listcommand doesn't print the environment type. To check it, in the Google Cloud console, go to Apigee > Management > Environments. See Apigee environment types.
Deploy the revision and pass the service account with
--service-account. Replace REVISION with the revision
number from Step 4:
gcloud beta apigee apis deploy REVISION \
--api=ai-gateway \
--environment=ENV \
--organization=ORG \
--service-account=SA_NAME@PROJECT_ID.iam.gserviceaccount.comDeployment is asynchronous. To check its status, which reports
PROGRESSING until it becomes READY, run:
gcloud apigee deployments describe \
--api=ai-gateway \
--environment=ENV \
--organization=ORG \
--format="value(state)"When the proxy is compiled, the spike-arrest and
verify-api-key features add their policies to the request PreFlow
(rate limiting first, then the API key check), and the gemini-target
feature adds the Agent Platform backend. After
the deployment completes, the proxy authenticates to
Agent Platform as your service account.
Step 6: Get an API key
The verify-api-key feature rejects any request that doesn't
carry a valid API key, so you need a key before you can call the proxy. An API
key is a credential of a developer app that is associated with an
API product containing this proxy. Complete the following tasks, which
are described in
Publishing
overview:
- Create
an API product that includes the
ai-gatewayproxy. In the product form, enter the following, and then click Save:- Name and Display name: any value, for example
ai-gateway-product. - Environment: the environment you deployed the proxy to (ENV).
- Access: Public. Leave Automatically approve access requests selected so that the API key is approved when you register the app.
- In the Operations section, click + ADD AN OPERATION and
set these fields:
- API proxy:
ai-gateway. - Path:
/. Requests go to the proxy's base path,/v1/gemini, with nothing after it. The path/matches the base path;/**matches only paths below it, so a request to/v1/geminifails with the erroroauth.v2.InvalidApiKeyForGivenResource. See Configuring resource paths. - Methods:
POST.
- API proxy:
- Leave API quota limit, LLM token quota limit, the
operation's Quota, and the LLM Operations section empty.
The
spike-arrestfeature in the proxy enforces the rate limit.
- Name and Display name: any value, for example
- Register an app developer.
- Register a developer app and select the API product when you create the app, so that the new key is associated with the product from the start.
Registering the app generates the key. To retrieve it, see Viewing an API key and secret.
Step 7: Call the proxy
Find your environment group's hostname as described in
Part 1, Step 5, then call the proxy at the base path
/v1/gemini. Pass the API key in the x-api-key header,
and send a Gemini
generateContent
request body:
curl -X POST https://HOSTNAME/v1/gemini \
-H "x-api-key: API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'Replace HOSTNAME with your environment group hostname and
API_KEY with the key from Step 6. A
successful response is the model's JSON output. Omitting the key returns an
authorization failure from the VerifyAPIKey policy, which confirms
that the verify-api-key feature is in effect. For other ways to
pass a key, see
Submitting
a request with a valid API key.
Next steps
- API proxy YAML configuration reference
- Configuring a proxy with YAML
- Deploying API proxies
- Publishing overview