Introducing the Apigee Migration Assessment Tool: Your roadmap to a smooth transition

[ashwinknaik]

Apigee Migration Assessment Tool

Migrating from Apigee Edge (OPDK or SaaS) to Apigee X or Hybrid? Our Apigee Migration Assessment Tool is here to make your journey as seamless as possible.

This powerful tool dives deep into your existing Apigee Edge environment, leaving no stone unturned. It then generates a comprehensive report packed with valuable insights and actionable recommendations tailored to your specific setup.

By leveraging these insights, you can streamline your migration process, anticipate potential roadblocks, and minimize disruptions to your operations.  The Apigee Migration Assessment Tool empowers you to plan with confidence and execute your migration with precision.

Prerequisites

You can run this tool locally or using Docker.

• Local: Requires installing Python libraries and dependencies.
• Docker: You can build the image yourself.

Local Setup

1. Install Graphviz: Follow the instructions at https://graphviz.org/download/
2. Install Python venv:

python3 -m pip install virtualenv==20.24.4

      3. Create and activate a virtual environment & Install Python dependencies:

python3 -m venv dev
source dev/bin/activate
pip install -r requirements.txt

Docker Setup

Use a pre-built Docker image:

Pull the docker image using docker pull

docker pull ghcr.io/apigee/apigee-migration-assessment-tool/apigee-migration-assessment-tool:latest

OR

Build the Docker image:

Use docker build and docker push to build and push the docker image to local registry.

docker build -t <image_name>:<tag> .
docker push <image_name>:<tag>

Apigee Permissions

Apigee Edge SAAS/OPDK

The tool requires permissions to export all objects from Apigee Egde. Hence assign the following permission to the relevant user.

• Read-only Organization Administrator

Refer: edge-built-roles

Apigee X/Hybrid

The tool requires readonly permissions to org, env & env objects. The tool also requires permissions to validate apis. Hence assign the below permissions to relevant user or service account.

• A built-in role roles/apigee.readOnlyAdmin
• A custom role with apigee.proxies.create permission

gcloud iam roles create ApigeeAPIValidator --project=<PROJECT_ID> \
--title="Apigee API Validator" \
--description="Apigee API Import validator" \
--permissions="apigee.proxies.create" --stage=Alpha

Refer: apigee-roles

Tool Usage

Complete Assessment

To assess all Apigee objects:

python3 main.py --resources all

Selective Assessment

To assess specific Apigee objects, use the --resources flag followed by a comma-separated list:

python3 main.py --resources <resource1>,<resource2>,...

Available resources:

• Environment Level: targetservers, keyvaluemaps, references, resourcefiles, keystores, flowhooks
• Organization Level: org_keyvaluemaps, developers, apiproducts, apis, apps, sharedflows

Examples

python3 main.py --resources targetservers,keyvaluemaps
python3 main.py --resources keystores,apps

Running the Tool

Prepare input.properties

Create an input.properties file in the same directory as the Python scripts. Please find sample inputs in the sample/inputs folder

• sample opdk input
• sample saas input

Refer the below table to set the required inputs in the input section of input.properties file.

Section	Input	Description
input	SOURCE_URL	Apigee OPDK/Edge Management URL
input	SOURCE_ORG	Apigee OPDK/Edge Organization
input	SOURCE_AUTH_TYPE	Apigee OPDK/Edge auth type , basic OR oauth
input	SOURCE_UI_URL	Apigee OPDK/Edge UI URL, use default
input	SOURCE_APIGEE_VERSION	APIGEE Flavor OPDK OR SAAS OR X OR HYBRID
input	GCP_PROJECT_ID	GCP Project ID running Apigee X/Hybrd. Trial orgs are supported
input	API_URL	Apigee API url, use default
input	GCP_ENV_TYPE	Apigee X/Hybrid desired environment type
input	TARGET_DIR	Name of directory to export apigee objects
input	SSL_VERIFICATION	Set to false , to ignore SSL verification else set it to true

Generate Apigee Edge SAAS/OPDK Auth Tokens:

Basic Auth:

export SOURCE_AUTH_TOKEN=`echo -n '<username>:<password>' | base64`

OAuth2/SAML:

Refer to the Apigee documentation for generating OAuth2 tokens.

export SSO_LOGIN_URL=https://login.apigee.com  # Example
export SOURCE_AUTH_TOKEN=$(get_token -u <user>:<password> -m xxxx) # Example using a helper script

Generate Apigee X/Hybrid Auth Tokens:

export APIGEE_ACCESS_TOKEN=$(gcloud auth print-access-token)

Run the Tool:

Local Run:

python3 main.py --resources <resources>

Example:

python3 main.py --resources all

Docker Run:

mkdir output
sudo chmod 777 output
export DOCKER_IMAGE="<image_name>:<tag>"
docker run --rm -v "$(pwd)/output:/app/target" \
    -v "$(pwd)/input.properties:/app/input.properties" \
    -e SOURCE_AUTH_TOKEN=$SOURCE_AUTH_TOKEN \
    -e APIGEE_ACCESS_TOKEN=$APIGEE_ACCESS_TOKEN \
    $DOCKER_IMAGE --resources all

 Note:
sudo chmod 777 output is required for ensuring the non-root user running the python code inside the docker image gets write privileges to your local machine as the volume is mounted to you local machine.

Example:

mkdir output
sudo chmod 777 output
export DOCKER_IMAGE="ghcr.io/apigee/apigee-migration-assessment-tool/apigee-migration-assessment-tool:latest"
docker run --rm -v "$(pwd)/output:/app/target" \
    -v "$(pwd)/input.properties:/app/input.properties" \
    -e SOURCE_AUTH_TOKEN=$SOURCE_AUTH_TOKEN \
    -e APIGEE_ACCESS_TOKEN=$APIGEE_ACCESS_TOKEN \
    $DOCKER_IMAGE --resources all

Accessing the Report and Visualization

• Assessment Report: qualification_report.xlsx in the TARGET_DIR (specified in input.properties).
  Please find sample assessment in the sample/outputs folder
• Visualization: visualization.html in the TARGET_DIR. Open this file in a web browser. Refer the sample visualization

Video recording

This video provides a step-by-step guide on how to use tooling. Whether you're a beginner or an experienced user, this video will equip you with the knowledge you need to make the most of this tool.

Contributing

Open-source tools thrive on community involvement, and GitHub is the perfect platform for collaboration. Whether you've encountered a bug, have a suggestion for a new feature, or simply want to share your thoughts on how the tool could be improved, creating an issue on the repository is the best way to do it. By clearly outlining the problem or idea, including steps to reproduce it if applicable, and labeling it appropriately, you'll be contributing directly to the tool's development and helping make it better for everyone. Don't hesitate to open an issue, no matter how small or large you think it might be – your input is valuable!