This is a tool to interact with Apigee APIs for Apigee hybrid and Apigee's managed offering. The tool lets you manage (Create,Get, List, Update, Delete, Export and Import) Apigee entities like proxies, products etc. The tools also helps you create Service Accounts in Google IAM to operate Apigee hybrid runtime.
apigeecli
is a binary and you can download the appropriate one for your platform from here. Run this script to download & install the latest version (on Linux or Darwin)
curl -L https://raw.githubusercontent.com/apigee/apigeecli/main/downloadLatest.sh | sh -
NOTE: The signature is not verified and the original zip is not preserved.
To test the signature of the binary, import the gpg public key:
gpg --recv-keys --keyserver keyserver.ubuntu.com A714872F32F34390
gpg: key A714872F32F34390: public key "apigeecli (apigeecli) <[email protected]>" imported
gpg: Total number processed: 1
gpg: imported: 1
Use curl or wget to download the zip and sig files. Verify using:
gpg --verify apigeecli_<signature-file>.sig apigeecli_<original-file>.zip
gpg: Signature made Thu 05 May 2022 05:58:11 PM UTC
gpg: using RSA key 72D11E3A3B1E9FE22110EC45A714872F32F34390
gpg: issuer "[email protected]"
gpg: Good signature from "apigeecli (apigeecli) <[email protected]>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 72D1 1E3A 3B1E 9FE2 2110 EC45 A714 872F 32F3 4390
The simplest way to get started with apigeecli
is
token=$(gcloud auth print-access-token)
apigeecli orgs list -t $token
If you are using the same GCP project for Apigee, then consider setting up preferences so they don't have to be included in every command. Preferences are written to the $HOME/.apigeecli
folder
project=$(gcloud config get-value project | head -n 1)
apigeecli prefs set -o $project
Subsequent commands can be like this:
token=$(gcloud auth print-access-token)
apigeecli orgs get -t $token #fetches the org details of the org set in preferences
apigeecli
can use the service account directly and obtain an access token.
apigeecli token gen -a serviceaccount.json
Parameters The following parameters are supported. See Common Reference for a list of additional parameters.
--account -a
(required) Service Account in json format
Use this access token for all subsequent calls (token expires in 1 hour)
apigeecli
caches the OAuth Access token for subsequent calls (until the token expires). The access token is stored in $HOME/.apigeecli
. This path must be readable/writeable by the apigeecli
process.
apigeecli token cache -a serviceaccount.json
or
token=$(gcloud auth print-access-token)
apigeecli token cache -t $token
The lastest container version for apigeecli can be downloaded via
docker pull ghcr.io/apigee/apigeecli:latest
See this page for other versions.
You must have an account on Apigee to perform any apigeecli
functions. These functions include: proxies, API Products, Environments, Org details etc.
You need to be familiar with basic concepts and features of Apigee such as API proxies, organizations, and environments.
For more information, refer to the Apigee API Reference.
Here is a list of available commands
The following environment variables may be set to control the behavior of apigeecli
. The default values are all false
APIGEECLI_DEBUG=true
enables debug logAPIGEECLI_SKIPCACHE=true
will not cache the access token on the diskAPIGEECLI_ENABLE_RATELIMIT=true
enables rate limiting when making Apigee APIs (at 1 API call every 100ms)APIGEECLI_NO_USAGE=true
does not print usage when the command failsAPIGEECLI_NO_ERRORS=true
does not print error messages from the CLI (control plane error messages are displayed)APIGEECLI_DRYRUN=true
does not execute Apigee control plane APIs
apigeecli
can generate API proxies from:
- OpenAPI 3.0 Specification
- GraphQL Schema
- A template/stub for Application Integration
- Cloud Endpoints/API Gateway OpenAPI 2.0 specification
apigeecli
allows the user to generate Apigee API Proxy bundles from an OpenAPI spec (only 3.0.x supported). The Apigee control plane does not support custom formats (ex: uuid). If you spec contains custom formats, consider the following flags
--add-cors=true
: Add a CORS policy--formatValidation=false
: this disables validation for custom formats.--skip-policy=false
: By default the OAS policy is added to the proxy (to validate API requests). By setting this to false, schema validation is not enabled and the control plane will not reject the bundle due to custom formats.
The following actions are automatically implemented when the API Proxy bundle is generated:
If the spec defines securitySchemes, for ex the following snippet:
components:
securitySchemes:
petstore_auth:
type: oauth2
flows:
implicit:
authorizationUrl: 'http://petstore.swagger.io/api/oauth/dialog'
scopes:
'write:pets': modify pets in your account
'read:pets': read your pets
api_key:
type: apiKey
name: api_key
in: header
is interpreted as OAuth-v20 (verification only) policy and the VerifyAPIKey policy.
These security schemes can be added to the PreFlow by enabling the scheme globally
security:
- api_key: []
Or within a Flow Condition like this
'/pet/{petId}/uploadImage':
post:
...
security:
- petstore_auth:
- 'write:pets'
- 'read:pets'
apigeecli
allows the user to dynamically set a target endpoint. These is especially useful when deploying target/backend applications to GCP's serverless platforms like Cloud Run, Cloud Functions etc. apigeecli
also allows the user to enable Apigee'e Google authentication before connecting to the backend.
apigeecli apis create -n petstore -f ./test/petstore.yaml --oas-target-url-ref=propertyset.petstore.url
This example dynamically sets the target.url
message context variable. This variable is retrieved from a propertyset file. It is expected the user will separately upload an environment scoped propertyset file with this key.
apigeecli apis create -n petstore -f ./test/petstore.yaml --oas-google-idtoken-aud-ref=propertyset.petstore.aud --oas-target-url-ref=propertyset.petstore.url
This example dynamically sets the Google Auth audience
and the target.url
message context variable. These variables are retrieved from a propertyset file. It is expected the user will separately upload an environment scoped propertyset file with these keys. If you do not wish to user a property to set these values later, you can use --oas-google-idtoken-aud-literal
to set the audience directly in the API Proxy.
While this example shows the use of Google IDToken, Google Access Token is also supported. To use Google Access Token, use the oas-google-accesstoken-scope-literal
flag instead.
apigeeli allow the user to add SpikeArrest or Quota policies. Since OpenAPI spec does not natively support the ability to specify such policies, a custom extension is used.
NOTE: This extension behaves differently when used with Swagger for Cloud Endpoints/API Gateway.
The following configuration allows the user to specify quota parameters in the API Proxy.
x-google-quota:
- name: test1 # this is appended to the quota policy name, ex: Quota-test1
interval-literal: 1 # specify the interval in the policy, use interval-ref to specify a variable
timeunit-literal: minute # specify the timeUnit in the policy, use timeUnit-ref to specify a variable
allow-literal: 1 # specify the allowed rate in the policy, use allow-ref to specify a variable
identifier-literal: request.headers.api_key # optionally, set an identifier. If not set, the proxy will count every msg. Identifiers are variables in apigee
NOTE: literals cannot be combined with variables.
The following configuration allows the user to derive quota parameters from an API Product
x-google-quota:
- name: test1 # this is appended to the quota policy name, ex: Quota-test1
useQuotaConfigInAPIProduct: Verify-API-Key-api_key # specify the step name that contains the consumer identification. Must be OAuth or VerifyAPIKey step.
The above configurations are mutually exclusive.
The following configuration allows the user to specify Spike Arrest parameters in the API Proxy.
x-google-ratelimit:
- name: test1 # this is appended to the quota policy name, ex: Spike-Arrest-test1
rate-literal: 10ps # specify the allowed interval in the policy, use rate-ref to specify a variable
identifier-ref: request.header.url #optional, specify msg ctx var for the identifier
See this OAS document for examples
apigeecli
allows the user to generate Apigee API Proxy bundles from a GraphQL schema. When generating a proxy, consider the following flags:
--basepath
: Specify a basePath for the GraphQL proxy--skip-policy=false
: By default the GraphQL policy is added to the proxy (to validate API requests). By setting this to false, schema validation is not enabled.--target-url-ref
: Specify a target endpoint location variable. For ex:--target-url-ref=propertyset.gql.url
implies the GraphQL target location is available in an environment scoped property set calledgql
and the key isurl
apigeecli
allows the user to generate an Apigee API Proxy bundle template for Application Integration. When generating the proxy, consider the following flags:
--trigger
: Specify the API trigger name of the Integration. This is also used as the basePath. Don't includeapi_trigger/
--integration
: Specify the Name of the Integration--name
: Specify the Name of the API Proxy
Cloud Endpoints and API Gateway use the extensions specified in an OpenAPI (FKA Swagger) document to apply policies. apigeecli
can use those extensions to generate a similar Apigee API Proxy bundle. When generating the proxy, consider the following flags:
--add-cors=true
: Add a CORS policy
- The
protocol
property inx-google-backend
is ignored. All upstream/backend is treated as http 1.1 - The
metrics
property inx-google-management
is not supported - The quota unit is ignored in
x-google-management
is ignored. See below for quota behavior - The extension
x-google-endpoints
is ignored. To add CORS, see above - Mutiple security requirements: If more than one security policy, regardless of the security type, is set on a path, then the first one is enabled. In the following examples,
/hello:
get:
operationId: hello
security:
- google_id_token: []
- api_key: []
or in the following case,
/hello:
get:
operationId: hello
security:
- google_id_token: []
api_key: []
it cannot be determined which policy is applied. It is best to avoid Swagger documents with such configurations.
- If more than one
x-google-jwt-locations
are specified, then the first one is used. In the following example,
x-google-jwt-locations:
# Expect header "Authorization": "MyBearerToken <TOKEN>"
- header: "Authorization"
value_prefix: "MyBearerToken "
# expect query parameter "jwt_query_bar=<TOKEN>"
- query: "jwt_query_bar"
query parameters are ignored. By default, if no location is specified, the JWT location is the Authorization
header and value_prefix is Bearer <token>
This is not an officially supported Google product