Introduction
Migrating API proxies from Apigee Edge to the more modern Apigee X or Apigee Hybrid platforms can be a complex and time-consuming process. It often involves manual, repetitive modifications to XML configurations to ensure compatibility. To streamline this transition, the apigee devrel team has developed the Apigee Proxy Bundle Modifier & Validator, a powerful open-source tool designed to automate the modification and validation of Apigee proxy bundles.
This command-line tool, written in Python, empowers developers to perform batch modifications across numerous proxy bundles simultaneously. By centralizing modification logic into a single configuration file, it ensures consistency, reduces human error, and dramatically accelerates migration timelines.
How the Tool Works
The tool’s power lies in its elegant separation of the modification logic from the core application. Instead of hard-coding changes, all operations are defined in a simple, human-readable policy.toml file.
-
Configuration-Driven Modifications: The core of the tool is a TOML configuration file (
policy.toml). Within this file, you define a set of rules that specify which XML files to target and how to modify them. -
XPath for Precision: Each rule uses XPath expressions to precisely target specific elements or attributes within the XML files of a proxy bundle.
-
Flexible Operations: The tool supports a variety of operations, including
-
Set/Replace
-
Prefix/Suffix
-
Conditional Prefix.
-
-
Preserving XML Formatting: The tool uses the robust lxml library to parse and rewrite XML files, ensuring that original formatting, comments, and structure are preserved.
-
Optional Validation: After modification, the tool can optionally upload the proxy bundles to the Apigee API for validation using Google Application Default Credentials (ADC).
-
Comprehensive Reporting: Upon completion, the tool generates a detailed Markdown report with a summary, validation results, and line-by-line diffs for all modified files.
Configuring the Modification Rules: The config.toml File
The heart of the tool is the policy.toml file, which acts as a blueprint for all modifications. It uses the TOML format for its simplicity and readability. You define a series of rules, and each rule tells the tool what to find, what to change, and how to change it.
Refer the policy_template.toml to understand the syntax of rule. You can have multiple such rules for multiple policies, ProxyEndpoint, TargetEndpoint etc.
Example Configuration:
Here is a comprehensive set of examples demonstrating how to define rules for various migration scenarios.
Set a AssignMessage transport attribute:
This rule finds any AssignMessage policy and sets the transport attribute from https to http.
[AssignMessage.transport]
xpath = ".//AssignTo"
target_type = "attribute"
attribute_name = "transport"
from = "https"
to = "http"
Set a AssignMessage transport attribute:
This rule finds any ServiceCallout policy and sets the HTTPTargetConnection property allow.http10 from true to false.
[ServiceCallout.disableHttp10]
xpath = ".//HTTPTargetConnection/Properties/Property[@name='allow.http10']"
target_type = "text"
from = "true"
to = "false"
You can find additional rule examples in policy.toml .
Getting Started
To get started on the using the tool.
git clone https://github.com/apigee/devrel
cd /tools/apigee-proxy-modifier-validator
pip install -r requirements.txt
gcloud auth application-default login # If doing validation
python modify_proxies.py --input-dir <path/to/input_bundles> \
--output-dir <path/to/output_bundles> \
--config-path <path/to/policy.toml> \
--report-file <path/to/output_report.md> \
[options]
Sample Report
Refer to a sample report generated by the tooling.
Conclusion
The Apigee Proxy Bundle Modifier & Validator is an invaluable asset for any organization planning a migration to Apigee X or Hybrid. By automating the most tedious aspects of the process, it not only accelerates migration but also significantly improves the quality and consistency of the resulting API proxies.
