By Vranda Sharma．Dec 16, 2022
This blog gives a high level overview of apigee-config-maven-plugin. In this blog we will showcase how to use the same for local apigee setups. Apart from this we will also share some tips and tricks useful 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 e.t.c. 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 . Since the plugin is not owned by Google, the documentation is not very detailed and hence this article could be a good start for anyone looking for creating an automated apigee configuration deployment solution. Let’s get started !!
Implementation
Step 1: Downloading and setting the apigee-maven-config-plugin.
For the local setup, maven is a pre-requisite 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 setup maven first. Post successful maven installation, the plugin can be setup 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 also directly download 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 about 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 an 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 <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 is showing profile named “dev”. Keep a note of the profile name as it will come handy in next step that will trigger the deployments.
Profile section snippet from shared-pom.xml
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 upon what configuration one wants the plugin to deploy when run for an apigee setup. The snippet below has <exceution> tags for all configurations and you can use as per your requirements.
Step 3: Prepare your json files for deployment
For this step, there are two approaches you can use. TL;DR 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 will use further 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 conguration in one place. The plugin by default looks for a file named edge.json for this approach. The sample edge.json file present in the repo includes a sample configuration set which on high level is broken down in three sections i.e. apiConfig, envConfig and orgConfig. There are multiple wrappers for different configuration under each of them. You can put the required config detail in json format under releavnt 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 is added in the pom file (described in step 2).
Dev env configuration snippet
Once the file is prepared with all the configuration required, you can use 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=createInstead of 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 seperate json files for each configuration i.e. developers, dev apps, kvms e.t.c. 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 resources directory . There are seperate 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 <excecution> tag in the pom file (described in step 2). Once you place the relavant config json’s 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/edgeStep 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 no, wohooooo… by now you would have successfully deployed your configuration and it’s time you login to your apigee UI and verify your deployed configuration.
Tricks and tips for a successful run
Remeber for apigee edge, developers, developer apps can be env specific configurations so make sure you add the json structure in the right heirarchy 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 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 please ensure to verify 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 end to end automate the deployments. Hope this was useful for you and for any further queries/concerns you can raise an issue here.
The original article published on Medium.
