LinkedIn
Twitter
This blog provides a high-level overview of apigee-config-maven-plugin and how to use the plugin for local Apigee setups. We’ll also share useful tips and tricks for locally setting up and testing the plugin.
Introduction
Apigee config maven plugin is a popular tool for creating automated deployments for non-proxy Apigee configurations, such as kvms, developers, developer apps, vhosts, etc. The plugin can be used for all Apigee offerings with slight tweaks in the plugin configuration, including Apigee X, Apigee hybrid, and Apigee Edge/Private-Cloud .
For anyone who wants to create an automated Apigee configuration deployment solution, this article is a great place to start. Let’s dive in!
Implementation
Step 1: Downloading and setting the apigee-maven-config-plugin
For the local setup, Apache Maven is a prerequisite and should be installed on the target machine. If you do not have Maven already installed on your machine, you can use this link to set it up. Once you’ve successfully installed Maven, the plugin can be set up from the open source repo, available on github. You can use the command below to clone the repo in a local folder.
git clone https://github.com/apigee/apigee-config-maven-plugin
Alternatively, you can download directly by hitting the download zip button from here. As a result, you will have the plugin downloaded in a folder, “apigee-config-maven-plugin”. Open the folder in a VS code window or any editor of your choice and go through the readme file once so you gain an idea of the basic approach.
Step 2: Edit the profile to point to your edge setup
For this step, look for the shared-pom.xml file (POM is a standard xml format file used by Maven that contains project-specific configuration/build info) under ../apigee-config-maven-plugin/samples/EdgeConfig.
In the file, look for the <profiles> section and update one profile with your host url, env, org, and auth type. After the update, your profile is ready to use. You can use multiple profiles for different orgs and setups. The snippet below shows a profile named “dev”. Keep a note of the profile name as it will come handy in the next step that will trigger the deployments.
https://gist.github.com/vrandasharma/6aabd52347c58b6f11cb3022445ea7f9#file-gistfile1-txt
Another important section of the shared-pom.xml is the <executions> section under <plugin> (id=apigee-config-maven-config). The <executions> tag has multiple <execution> tags, typically one for each configuration.
Below is a snippet of the same. Closely looking at each execution, you see that it is linked with one goal, that is essentially the configuration whose deployment it indicates. You can add or remove the <execution> tags in this section based on what configuration one wants the plugin to deploy when run for an Apigee setup. The snippet below has <execution> tags for all configurations and you can use as per your requirements.
https://gist.github.com/vrandasharma/fc8f2080a5e6df02f68e8aef0f1caa08#file-gistfile1-txt
Step 3: Prepare your json files for deployment
For this step, there are two approaches you can use. The first approach specifies how to use a single file for deployment, while the second approach is the more standard approach that manages one json file per configuration.
Below is a summary of all the Maven parameters we’ll use in the Maven deployment commands.
Ptest -> Indicates the profile test (described in step 2)
Denv -> Apigee environment
Dorg -> Apigee org name
Dhosturl -> Apigee host url
Dusername -> Apigee username
Dpassword -> Apigee password
Dapigee.config.dir -> The relative path of the directory containing json files for org/env/api
Dapigee.config.options -> Scope of the apigee-config-maven-plugin. There are multiple values of the scope (i.e. create, update, sync, and delete). Their purpose and interpretation is listed below. You can use these options to meet your requirements.
Dapigee.config.options
none - No action (default).
create - Create when not found. Pre-existing config is NOT updated even if it is different.
update - Update when found; create when not found, updates individual entries for kvms. Refreshes all config to reflect edge.json.
delete - Delete all config listed in edge.json.
sync - Delete and recreate.
Approach 1 : This approach is to use one single file with all configuration in one place. The plugin by default looks for a file named edge.json. The sample edge.json file present in the repo includes a sample configuration set, which is broken down into three sections, i.e. apiConfig, envConfig, and orgConfig.
There are multiple wrappers with a different configuration under each of them. You can put the required config detail in json format under the relevant tag. Below is a snippet of a small configuration for adding kvms, developers, and developer apps in env “dev”.
Please ensure that for each configuration you add the relevant <execution> tag in the pom file (described in step 2).
https://gist.github.com/vrandasharma/2b22d27014e4fdb28491305d071dbb78#file-gistfile1-txt
Once the file is prepared with all the configuration required, you can use the below command to initiate the deployment. Before running the command you must cd into the folder ../apigee-config-maven-plugin/samples/EdgeConfig.
mvn install -Ptest -X -Dhosturl={apigee_url} -Dorg={org} -Denv={env} -Dusername={username} -Dpassword={password} -Dapigee.config.options=create
Instead of the default edge.json file, if you want to use your custom json file you can use -Dapigee.config.file=<path-to-config-file> parameter in the command above.
Approach 2: Approach 2 is to use separate json files for each configuration (i.e. developers, dev apps, kvms, etc.). This is the recommended way of using the plugin, as the maintenance is easy and the structure is clean.
For this, json files are created for each configuration and are placed under the resources directory. There are separate directories for org, api, and env level config json’s under ../resources/edge.
Please ensure that for each json configuration file, you add the relevant <execution> tag in the pom file (described in step 2). Once you place the relevant config json under these directories, you can run the below command to initiate the deployment. Before running the command you must cd into the folder ../apigee-config-maven-plugin/samples/EdgeConfig.
mvn install -Ptest -Dorg={org} -Dhosturl={apigee_url} -Denv={env} -Dusername={username} -Dpassword={password} -Dapigee.config.options=create -Dapigee.config.dir=resources/edge
Step 4: Test the deployment
If you encountered any error in step 3, make sure you have configured the json tags carefully and read the error on console for any syntax issues. Below is a snippet of the json error in the json file.
If not, woo hoo! By now you would have successfully deployed your configuration and it’s time for you to log into your Apigee UI and verify your deployed configuration.
Tips and tricks for a successful run
Remember for Apigee Edge, developers and developer apps can be env specific configurations, so make sure you add the json structure in the right hierarchy if you are using resource files or keep them under envConfig if you are using edge.json file.
Another important thing is to deploy the configuration in the right order. For example, you first need to add developers to deploy developer apps on behalf of the developer. This can be done by ensuring the right order of <execution> tags in the shared-pom.xml file (described in step 2).
Also make sure that the path of shared-pom.xml in the pom.xml is correct. Look for the tag below and ensure the relative path is correct. <relativePath>../shared-pom.xml</relativePath>.
You can also add the script in the CI/CD pipeline to automate the deployments end-to-end.
We hope this was useful for you! For any further questions or concerns, you can leave a comment below or raise an issue here.
For more information, best practices, and tutorials with Apigee, see Apigee Product Articles here and the Q&A Forum here.