CA API Gateway 9.1

9.4 9.1

Version Control Example

This topic describes how to use the Gateway Migration Utility (GMU) with a version control tool when developing policies and services for the gateway. The workflow described here can be used with most version control systems. For the examples, Subversion is used.
gateway91
This topic describes how to use the Gateway Migration Utility (GMU) with a version control tool when developing policies and services for the
CA API Gateway
. The workflow described here can be used with most version control systems. For the examples, Subversion is used.
You should have good working knowledge of the
CA API Gateway
 and the Gateway Migration Utility.
Workspace Assumptions
When using the GMU, it is common practice to have your connection arguments in a properties file. This topic assumes that you have an argument properties file containing the properties needed to connect to a Gateway. For example:
host=myGatewayHost
username=myGatewayAdmin
password=7Bywx28jIME.jPobbMOtyGdEcqU3MLp9sA
port=8443
encryptionPassphrase=WxCXwYpPWf0.CXCLNHYTxJBvUfwtSJkAjw
This topic also assumes that GMU is running on a Unix machine, the following locations:
  • GMU scripts are located at 
    ~/gmu
  • svn repository is located at
    ~/otk_mag
Set Up and Initial Commit
Before continuing, perform an initial check into your version control system. This applies whether you are starting from an existing set of policies and services or from a new Gateway.
Migrate out your Gateway into a versioned folder with this command:
gmu/GatewayMigrationUtility.sh migrateOut -z gateway.properties -folderName / -d otk_temp -f directory --defaultAction NewOrUpdate && (cd otk_temp && tar c .) | (cd otk_mag  && tar xf -) && rm -rf otk_temp
This command migrates out to
otk_temp
 and then copies the result into
otk_mag
.
Tip:
 This migration/copy is necessary because if you migrate directly into
otk_mag
, the GMU first deletes everything from
otk_mag
 before migrating. This will remove files required by the version control system.
Understanding the migration command
gmu/GatewayMigrationUtility.sh migrateOut -z gateway.properties -folderName / -d otk_temp -f directory --defaultAction NewOrUpdate
•    This migrates out the root folder ‘/’ into a directory named
otk_temp
(cd otk_temp && tar c .) | (cd otk_mag  && tar xf -)
•    This copies all files from
otk_temp
 to
otk_mag
, replacing any existing files. (There are many other ways to copy files, this is just one example.)
rm -rf otk_temp
•    This removes the
otk_temp
 directory
In the
otk_mag
 directory, there are two folders:
dependencies
rootFolder
There are also two XML files:
dependencies.xml
mappings.xml
Check this bundle into your version control system.
If you migrate out a full gateway ("--all" parameter is used), there will be many differences with auto generated role IDs. To deal with these, remove the auto generated roles from the export. Entities with secrets also always have a new bundle key when re-exported.
Check Out from Version Control System and Set Up a New Gateway
This assumes starting with a brand new
CA API Gateway
 that is licensed and has the Gateway REST Management Service published. For more information, see Publish Internal Service.
Check out the bundle from your version control system. Then, import it into your Gateway with this command:
gmu/GatewayMigrationUtility.sh migrateIn -z gmu/local.properties -b otk_mag -r result.xml
This migrates in the bundle located in the folder
otk_mag
 and saves the results to
result.xml
.
Dealing with Environmental Properties
To handle environmental properties that are different across environments, you can templatize the bundle. Properties that may require templatization include: JDBC connection settings, HTTP connection settings, passwords, etc.
  1. Templatize your bundle with this command:
    gmu/GatewayMigrationUtility.sh template -b otk_mag -t otk_mag/template.properties
    This tempatizes the bundle located in
    otk_mag
     and saves the template properties in
    template.properties
    .
  2. Templatizing everything in the bundles includes a large number of properties. To improve usability, reduce the number of templatized properties.
    1. Open the
      template.properties
       file in a text editor.
    2. Extract only the properties that you want to templatize and place them in a new file. (Remove them from
      template.properties
      .)
    For example, if templatizing a single JDBC connection and its secure password, your extracted template properties might look like this:
    #jdbc_connection OTK_MAG
    template.jdbc_connection.OTK_MAG.Extension.ConnectionProperties.user.StringValue=OTK_MAG
    template.jdbc_connection.OTK_MAG.Extension.JdbcUrl=jdbc:mysql://devhost1:3306/otk
    template.jdbc_connection.OTK_MAG.Extension.ConnectionProperties.password.StringValue=myDevPass
  3. With the environmental properties extracted to a separate template file, detemplatize with this command:
    gmu/GatewayMigrationUtility.sh detemplate -b otk_mag -t otk_mag/template.properties
    This detemplatizes the bundle located at
    otk_mag
     with the template properties in the
    otk_mag/template.properties
     file.
    All properties should now be detemplatized, except the user and host name on the JDBC connection and the bundle key and password value in the secure password.
  4. To migrate in the bundle from above:
    gmu/GatewayMigrationUtility.sh migrateIn -z gmu/local.properties -b otk_mag -r result.xml --template otk_mag/environment.properties
    This migrates in the bundle located in the
    otk_mag
     directory and applies the template properties in
    otk_mag/environment.properties
    .
  5. To test the policies and services, check them out from source control, then import them into the Gateway using the custom environment.properties file:
    gmu/GatewayMigrationUtility.sh migrateIn -z gmu/local.properties -b otk_mag -r result.xml --template otk_mag/qa_environment.properties
Detemplatizing a Bundle
You can partially detemplatize a bundle with the following script:
#!/bin/bash
 
if [[ -z "$1" || -z "$2" ]] ; then
    echo "Need to specify a bundle and template.properties: $( basename $0 ) <bundle> <template.properties>"
    exit 1
elif [ ! -e "$1" ]; then
    echo "Bundle does not exist: $1"
    exit 1   
elif [ ! -r "$1" ]; then
    echo "Cannot read bundle $1"
    exit 1
elif [ ! -e "$2" ]; then
    echo "Template properties file does not exist: $2"
    exit 1   
elif [ ! -r "$2" ]; then
    echo "Cannot read file template properties file $2"
    exit 1
fi
 
scriptDir=$(dirname $0)
workingDir="templateWork"
mkdir -p ${workingDir}
bundle="$1"
templateProperties="$2"
fullTemplateFile=`mktemp -p ${workingDir} -t fullTemplate.XXXXXXXXXX.properties`
propertiesListFile=`mktemp -p ${workingDir} -t propertiesList.XXXXXXXXXX.properties`
reducedTemplateFile=`mktemp -p ${workingDir} -t reducedTemplate.XXXXXXXXXX.properties`
 
#templatize the bundle
${scriptDir}/GatewayMigrationUtility.sh template -b ${bundle} -t ${fullTemplateFile}
 
#find the list of template properties to leave from the given template properties file
awk '/^[:blank:]*[^#].*=.*$/ {print substr($0, 0, index($0, "=")-1)}' ${templateProperties} > ${propertiesListFile}
 
# remove all the template properties from the full template properties file
grep -v -F -f ${propertiesListFile} ${fullTemplateFile} > ${reducedTemplateFile}
 
#partially detemplatize the bundle
${scriptDir}/GatewayMigrationUtility.sh detemplate -b ${bundle} -t ${reducedTemplateFile}
Assuming a script name
templatizeParial.sh
, you run it as follows:
gmu/templatizePartial.sh bundle default.properties
This detemplatizes only the properties listed in
default.properties
 in the bundle.
This script can be used in combination with the
migrateOut
 command when migrating out into your svn directory:
gmu/GatewayMigrationUtility.sh migrateOut -z gateway.properties -folderName / -d otk_temp -f directory --defaultAction NewOrUpdate && gmu/templatizePartial.sh otk_temp otk_mag/default.properties && (cd otk_temp && tar c .) | (cd otk_mag  && tar xf -) && rm -rf otk_temp

Content feedback and comments