apigee-edge-maven-plugin is a build and deploy utility for building and deploying the Apigee ApiProxy's/Application bundles into Apigee Platform. The code is distributed under the Apache License 2.0.
NOTE: Log4J libraries are upgraded to v2.17.1 in v2.2.2
The samples folder provides a Readme with Getting Started steps and commands to hit the ground quickly.
Learn more, check out this video! Ask the Expert
You will need the following to run the samples:
<dependency>
<groupId>io.apigee.build-tools.enterprise4g</groupId>
<artifactId>apigee-edge-maven-plugin</artifactId>
<version>1.x</version>
</dependency><dependency>
<groupId>io.apigee.build-tools.enterprise4g</groupId>
<artifactId>apigee-edge-maven-plugin</artifactId>
<version>2.x</version>
</dependency>Often the most difficult and confusing aspect of application development is figuring out how to build a common framework for creating new applications. Over time, development teams have started using tools like Maven, Ant and Ivy to automate some of these functions. This plugin uses the Maven plugin for deploying bundles to the Apigee platform.
Apigee bundles can be described as a zipped file system composed of configuration, scripts and code. The file system when extracted is composed of the following structure.
|-apiproxy/
|-proxies
|-resources
|-policies
|-targetsInstructions for creating a new API proxy can be found at this link
https://cloud.google.com/apigee/docs/api-platform/develop/ui-create-proxy
Instructions for exporting your API via an API can be found at this link
https://cloud.google.com/apigee/docs/api-platform/fundamentals/download-api-proxies#download
To export you API via Apigee select the organization that contains the proxy you wish to export. From the navigation bar on the top, under APIs select the API Proxies. Select the proxy, on the far left of the screen, under the drop down menu titled Project, select Download Current Revision.
Follow below steps to set up your local development environment
And you are ready for deploy to Apigee using the plugin
Below is the recommended structure for the project. However only the folder structure below the folder gateway is mandatory
|-name-of-root (typically company name)
|-archive/
|-docs
|-src
|-binaries/
|-build-artifacts/
|-docs/
|-customer
|-reference
|-solution
|-src/
|-analytics
|-gateway/ ***
|-parent-pom
|-test-app/
|-apiproxy/
|-proxies
|-resources/
|-py
|-policies
|-targets
|-java
|-portal
|-testThe API bundle will come zipped, use the unarchiving utility of your choice to unzip the file.
Once unzipped you will have a folder named apiproxy, this folder contains all of the configuration for your proxy and the folder structure needed for re-importing of the configuration.
The composition of the folder can be described as below.
| File/Folder | Purpose |
|---|---|
| {ApiName}.xml | A file that contains descriptors for the content |
| policies/ | A folder that contains all policy xml files |
| proxies/ | A folder that contains information about your proxy configurations (inbound) |
| targets/ | A folder that contains information about target configurations (outbound) |
| resources | A folder that contains any scripts (java, jsc, py, node) |
Note: when creating scripts, place your script/jar files in the proper folders based on the script type (e.g. JavaScript in jsc, node.js in node, java in java).
In a standard configuration typically we have parent-pom (pom.xml inside the parent-pom directory) and a child pom (pom file at the peer level as folder apiproxy).
The contents of the parent pom folder will contain a single pom.xml file. This file typically contains most of the configuration of Maven and the plugin, it also contains credentials for the Apigee platform.
In case of manual creation of Maven compatible file structure, "parent-pom" directory should be in peer level with other application folders. Here we configure information that is common across multiple apiproxys. Eg: Profile configurations which has the org/env info etc.
Refer parent-pom template parent-pom
Child-pom: Here we configure all the details specific to the particular proxy.
Refer child-pom template child-pom.
The config.json contains rules to perform build time configuration update. This JSON file's root object is "configurations" and is an array of proxy configurations scoped to an environment.
Note: it is important that the name of the configurations match the name of the profiles in the parent-pom.
For instance in the example below you have two configurations one for the test profile and one for the production profile. This example also shows how you can use xpath to replace environment specific settings.
Refer config.json template config.json
/src/gateway/proxy-dir
(run the command from the directory same as child pom)
mvn apigee-enterprise:deploy -P<profile> -Dfile={file}The default configuration is "override" and in this option, the plugin polls to check if the deployment is complete across all pods. If you do not want the plugin to poll, please pass -Dapigee.options=async. This is available in v2.0.2 and later
mvn apigee-enterprise:deploy -P<profile> -Dfile={file} -Dapigee.options=asyncFor example:
mvn apigee-enterprise:deploy -P prod -Dfile={file}You can also pass the bearer token to deploy (available from v2.0.1 and later)
mvn clean install -P{profile} -Dbearer=${bearer} -Dapigee.options={option}For example using gcloud
mvn clean install -P{profile} -Dbearer=$(gcloud auth print-access-token) -Dapigee.options={option}NOTE: This option is available in Apigee X and Apigee hybrid 1.6+
If the API Proxy makes a callout to a Google API, Apigee now supports generating the access token or ID Token by just passing the service account email to the deployment API. For more info on the policy and HTTPTargetConnection config, check out Authentication.
mvn clean install -P{profile} -Dbearer=$(gcloud auth print-access-token) -DgoogleTokenEmail={ACCOUNT_ID}@{PROJECT}.iam.gserviceaccount.comFor more info check out Using Google authentication using Apigee
NOTE: Please make sure that you have the following config in your Maven profile
<apigee.googletoken.email>${googleTokenEmail}</apigee.googletoken.email>To delete the entire proxy or sharedflow, pass the options as clean
mvn clean install -P{profile} -Dbearer=$(gcloud auth print-access-token) -Dapigee.options=cleanTo just import the proxy or sharedflow without activating, pass the options as inactive
mvn clean install -P{profile} -Dbearer=$(gcloud auth print-access-token) -Dapigee.options=inactiveTo promote an existing revision deployed to an Apigee org you can use the apigee-enterprise:promote goal
The promote goal allows the following options:
mvn apigee-enterprise:promote -P${profile} -Dbearer=$(gcloud auth print-access-token)For example let's say the latest revision number of a proxy is 5 (whether deployed or not), the above command will deploy that revision to the environment configured in the Maven profile
mvn apigee-enterprise:promote -P${profile} -Dbearer=$(gcloud auth print-access-token) -Dapigee.promote.revision=${REV}For example, let's say you want a specific revision (Revision 3) to be deployed to an environment, you just need to pass -Dapigee.promote.revision=3. The plugin will deploy that revision to the environment configured in the Maven profile
mvn apigee-enterprise:promote -P${PROFILE} -Dbearer=$(gcloud auth print-access-token) -Dapigee.promote.sourceEnv=${SOURCE_ENV}For example, lets say Revision 6 is deployed to dev environment and you want to promote that revision to qa environment. You can just pass -Dapigee.promote.sourceEnv=dev. The plugin will find the deployed revision from the source environment passed and deploy that revision to the environment configured in the Maven profile
The following entries in some XML file elements could be changed to match the customer's environment:
Shared Flow bundles can be described as a zipped file system composed of policies, steps and code. The file system when extracted is composed of the following structure.
|-sharedflowbundle/
|-policies
|-sharedflowsThe build steps and the options available for building and deploying Shared Flows are the same as API Proxy. The samples has an example of a standard sharedflow with the folder structure and the parent pom file. The only key difference between the API Proxy and the Shared Flow is a new property as part of the profiles.
<apigee.apitype>sharedflow</apigee.apitype>
This is required to differentiate the build and deployment process.
Supported from v2.5.0
Please refer to this doc that explains how to setup proxy settings in your settings.xml usually in your $HOME/.m2 directory. Only https protocol is supported
Refer Guide for Plugin Developers
The plugin is initially developed by Santany Dey. With major contributions from Sai Saran Vaidyanathan, Madhan Sadasivam. The plugin is open sourced by Priyanky Thomas.
Issues filed on Github are not subject to service level agreements (SLAs) and responses should be assumed to be on an ad-hoc volunteer basis. The Apigee community board is recommended as for community support and is regularly checked by Apigee experts.
Apigee customers should use formal support channels for Apigee product related concerns.
This is not an officially supported Google product.