כלי לזיהוי שינויים ב-Edge for Private Cloud 4.54.00

כלי לזיהוי שינויים

פיתחנו כלי לזיהוי שינויים כדי לזהות שרתי proxy, כללי מדיניות, תהליכים משותפים וקובצי JAR של משאבים (ברמת שרת ה-proxy, הסביבה או הארגון) ב-Apigee שעשויים להיות מושפעים במהלך המעבר ל-Edge for Private Cloud 4.54.00 ואחריו. הכלי הזה יוצר דוח שמפרט את ה-proxies שנפרסו, את הרכיבים המשותפים ואת קובצי ה-JAR של המשאבים שהשינויים משפיעים עליהם, ומספק הפניה למדריכים ולשיטות ספציפיים שרלוונטיים ל-proxies או לרכיבים המשותפים שזוהו.

דרישות מוקדמות

  1. כדי להפעיל את הכלי הזה, צריך מחשב מבוסס RHEL או Rocky Linux (ראו דרישות ההתקנה של Edge).
  2. כדי שהסקריפטים של הכלי יוכלו לפעול, צריך להתקין JRE 8 או גרסה מתקדמת יותר ולהגדיר אותו בצורה נכונה במכונה המארחת.
  3. הכלי דורש גישה לרשת לנקודת הקצה (כתובת ה-URL) של שרת הניהול ופרטי כניסה חוקיים של אדמין לצורך אימות ואחזור נתונים.
  4. הכלי דורש גישה לספריית עבודה ייעודית (לדוגמה, /tmp) עם מספיק מקום בכונן והרשאות קריאה/כתיבה מתאימות להורדת חבילות, ליצירת יומנים ולאחסון פלט.
  5. (אופציונלי) כשמשדרגים מגרסה 4.53.00, הכלי דורש קובץ LDIF שנוצר באמצעות הפקודה ldapsearch בקטע OpenLDAP change - Extract LDAP data כדי לזהות RDN ארוכים שאורכם עולה על 241 תווים או בייטים.

הפעלת הכלי

אחרי שמוודאים שכל הדרישות המוקדמות מתקיימות, מורידים את הכלי מהמאגר של Apigee באמצעות פרטי הכניסה ל-Apigee, ומחלצים את הארכיון שהורדתם:

curl -u uName:pWord https://software.apigee.com/apigee/change-detector/change-detector-for-4.54.00_1.0.0.zip -o /tmp/change-detector-for-4.54.00_1.0.0.zip
 
unzip /tmp/change-detector-for-4.54.00_1.0.0.zip

אחרי שההורדה תסתיים, תוכלו להריץ את הפקודה הבאה כדי לראות את כל האפשרויות הזמינות בכלי:

./change-detector --help

כדי להריץ את הכלי, משתמשים בפקודה הבאה ומחליפים את ה-placeholder במידע שלכם:

export APIGEE_PASSWORD=YOUR_PASSWORD
./change-detector --username YOUR_USERNAME --mgmt-url MGMT_URL --source-version SOURCE_VERSION

מציינים --source-version 4.53.01 כשמשדרגים ישירות מ-Edge for Private Cloud 4.53.01 כדי לסרוק שינויים ב-Java 21. אם משדרגים מגרסה 4.53.00, צריך לציין את --source-version 4.53.00 כדי לבצע סריקה מצטברת שכוללת גם את המדיניות שהוצאה משימוש בגרסה 4.53.01 וגם את השינויים ב-Java 21.

הכלי יוצר פלט בפורמט CSV או JSON שאפשר לבדוק אותו ישירות או לייבא אותו לאפליקציות של גיליונות אלקטרוניים כמו Google Sheets.

הסבר על הפלט של הכלי

הדוח כולל את העמודות הבאות:

ארגון

שם הארגון שבו נמצא הארטיפקט. בשינויים ב-OpenLDAP, זהו None.

סביבה

הסביבה הספציפית (לדוגמה, dev, ‏ test, ‏ prod) בתוך הארגון. ב-JAR ברמת הארגון, השדה הזה הוא N/A. בשינויים ב-OpenLDAP, זהו None.

שם שרת ה-Proxy

השם של proxy ל-API או של תהליך משותף. במשאבי JAR ברמת הארגון, מוצג שם הארגון. במשאבי JAR ברמת הסביבה, מוצג שם הסביבה. בשינויים ב-OpenLDAP, בשדה הזה מוצגת ישות ה-LDAP של ה-RDN.

היקף

מציין את ההיקף והרמה של הארטיפקט שנסרק:

  • ‫proxy-level-jar: קובץ משאב JAR שהועלה ברמת שרת ה-proxy (בקטע /resources/java).
  • ‫env-level-jar: קובץ משאב JAR שהועלה ברמת הסביבה (ראו קובצי משאבים).
  • ‫org-level-jar: קובץ משאבים מסוג JAR שהועלה ברמת הארגון.
  • ‫proxy: מדיניות או הגדרה בגרסה של proxy ל-API.
  • ‫sharedflow: מדיניות או הגדרה בגרסה של תהליך משותף.
  • ‫ldif: קובץ OpenLDAP LDIF (לבדיקות OpenLDAP).

גרסה קודמת

מספר הגרסה הספציפי של ה-proxy ל-API או של התהליך המשותף. לקובצי JAR ברמת הסביבה או הארגון, השדה הזה הוא N/A. בשינויים ב-OpenLDAP, זהו None.

שם מדיניות

השם של המדיניות הספציפית שזוהתה כבעיה פוטנציאלית (לדוגמה, JavaCallout-ValidateAccount או OASValidation-1). במשאבים ברמת הארגון, בשדה הזה מוצג הערך N/A (Organization Resource). במשאבים ברמת הסביבה, בשדה הזה מוצג הערך N/A (Environment Resource). בשינויים ב-OpenLDAP, זהו None.

סוג מדיניות

סוג המדיניות (לדוגמה, java-callout או OASValidation). במקרה של שינויים ב-OpenLDAP, הסוג הוא None.

גרסת המקור

גרסת המקור של OPDK שהוגדרה לסריקה (4.53.00 או 4.53.01).

המשאב המושפע

תיאור של המשאב או הספרייה הספציפיים שזוהו:

  • לזיהויים של קריאות חוזרות (callout) ב-Java 21: השם המדויק של קובץ ה-JAR המושפע (לדוגמה, order-transform.jar או corba-callout.jar).
  • מידע על הוצאה משימוש של גרסה 4.53 מדור קודם: deprecated library detected for NAME_OF_THE_AFFECTED_JAVA_CALLOUT_JAR.
  • בזיהויים של OAS,‏ JSONPath או OpenLDAP: רכיב המדיניות או המשאב הספציפיים (לדוגמה, oas content type handling,‏ wildcard expression או LDAP RDN exceeds 241 characters).

הסיבה לזיהוי

מספק מידע אבחוני מפורט על הסיבה לכך שהפריט סומן:

  • לזיהויים של קריאות החוצה ב-Java 21: המחלקה הספציפית, ספריית היעד להחלפה (אם רלוונטי) והגורם הבסיסי (לדוגמה, Class: javax.xml.bind.JAXBContext | Target Library: jakarta.xml.bind-api-2.3.3.jar | Root Cause: ClassNotFoundException: JAXB API was removed from Java SE in Java 11 (JEP 320)). אם מזוהות כמה בעיות באותו JAR, הן מאוחדות ומופרדות באמצעות ;.
  • להוצאה משימוש של גרסה 4.53 הקודמת: רשימה של מחלקות שהופנו מספריות שהוצאו משימוש (לדוגמה, ['Detected use of class CLASS_NAME from JAR_NAME']).
  • לאימותים של OAS: המשתנה שצוין בתג Source (לדוגמה, Source=response).
  • ב-JSONPath: הביטוי המדויק שסומן.
  • ‫OpenLDAP: ה-RDN של ישות ה-LDAP הספציפית שחורג מ-241 בייטים או תווים.

מידת הוודאות של ההשפעה

השדה הזה מציין את רמת הסמך שלפיה הכלי זיהה גורם שמונע את השדרוג. הערכים מופיעים באותיות רישיות:

  • ‫HIGH: הכלי זיהה שינוי לא תואם (למשל קריאה למחלקה שהוסרה לצמיתות כמו javax.xml.bind.JAXBContext או sun.misc.BASE64Encoder, או RDN של OpenLDAP שעולה על 241 בייט). יש סבירות גבוהה מאוד לכשל בזמן ריצה (ClassNotFoundException או NoClassDefFoundError) אלא אם הבעיה תתוקן.
  • ‫MEDIUM: הכלי זיהה דפוס שמחייב בדיקה של המפתח ואימות פונקציונלי:
    • לקריאות ל-Java: מסומנות ב-METHOD_SIGNATURE_MODIFICATION (לדוגמה, org.w3c.dom.Document), כשהמחלקה קיימת ב-Java 21 אבל יכול להיות ששיטות ספציפיות שונו או הוצאו משימוש.
    • במדיניות OASValidation: מסומן כשמשתמשים במשתני זמן ריצה דינמיים ברכיב <Source> (לדוגמה, Source=response), מה שמחייב לתעד את המעקב כדי לצפות במשתנים שנפתרו במהלך הפעלת שרת ה-proxy.

דוחות זיהוי לדוגמה

דוח סריקה ממוקדת של Java 21‏ (--source-version 4.53.01)

בדוגמה הבאה מוצג פלט של דוח לשדרוג מ-OPDK 4.53.01 ל-4.54.00:

ארגון סביבה שם ה-Proxy היקף גרסה קודמת שם מדיניות סוג מדיניות גרסת המקור המשאב המושפע הסיבה לזיהוי מידת הוודאות של ההשפעה
my-org prod order-processing proxy-level-jar 12 JavaCallout-ParseXml java-callout 4.53.01 jaxb-callout.jar Class: javax.xml.bind.JAXBContext | Cause: ClassNotFoundException..... HIGH
my-org stage legacy-corba-bridge proxy-level-jar 1 JavaCallout-CorbaClient java-callout 4.53.01 corba-callout.jar Class: org.omg.CORBA.ORB | Cause: ClassNotFoundException..... HIGH
my-org prod prod env-level-jar N/A N/A (Environment Resource) java-callout 4.53.01 env-security-utils.jar Class: sun.misc.BASE64Encoder | Cause: ClassNotFoundException..... HIGH
my-org N/A my-org org-level-jar N/A N/A (Organization Resource) java-callout 4.53.01 cglib-nodep-2.2.jar Class: net.sf.cglib.proxy.Enhancer | Cause: IllegalArgumentException..... HIGH
my-org prod invoice-parser proxy-level-jar 5 JavaCallout-ParseInvoice java-callout 4.53.01 invoice-dom.jar Class: org.w3c.dom.Document | Cause: Modified methods in Java 21..... MEDIUM
my-org prod payment-gateway proxy-level-jar 3 JavaCallout-SignToken java-callout 4.53.01 payment-lib.jar Class: com.mycompany.crypto.OldProvider | Target: custom-crypto-3.0.jar..... HIGH

דוח סריקה מצטבר (--source-version 4.53.00)

בדוגמה הבאה מוצג פלט של דוח לשדרוג מ-OPDK 4.53.00 ל-4.54.00:

ארגון סביבה שם ה-Proxy היקף גרסה קודמת שם מדיניות סוג מדיניות גרסת המקור המשאב המושפע הסיבה לזיהוי רמת הוודאות של ההשפעה
my-org prod customer-portal proxy 3 ValidateOpenAPISpec OASValidation 4.53.00 oas content type handling Source=response MEDIUM
my-org prod accounts-api proxy-level-jar 4 JavaCallout-ValidateAccount java-callout 4.53.00 deprecated: custom-validator.jar..... ['Detected use of class org.apache.commons.beanutils.....'] HIGH
my-org prod order-processing proxy-level-jar 12 JavaCallout-ParseXml java-callout 4.53.00 jaxb-callout.jar Class: javax.xml.bind.JAXBContext | Cause: ClassNotFoundException..... HIGH
my-org None None ldif None None None 4.53.00 LDAP RDN exceeds 241 characters cn=very-long-rdn-name-exceeding-limit..... HIGH

במאמר אסטרטגיות לפתרון בעיות מוסבר איך לפתור את הבעיות שזוהו.