שינויים ב-Edge for Private Cloud 4.54.00

סקירה כללית של השינויים

בגרסה 4.54.00 של Edge for Private Cloud יש כמה שינויים שמשפרים את מצב האבטחה של הפלטפורמה, ועדכונים לרכיבי הפלטפורמה כדי להפעיל אותם עם Java 21. שניים מהקטעים הבאים עוסקים בשינויים האלה:

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

שינויים במדיניות בנושא Java Callout

ב-Edge for Private Cloud 4.54.00, רכיבי ליבה של הפלטפורמה – כולל מעבד ההודעות, שרת הניהול והנתב – מתעדכנים כדי לפעול ב-Java 21 LTS. ‫Java 21 מודרניזציה של פלטפורמת Java, שכוללת הסרה של מודולים מדור קודם של Java EE ו-CORBA ‏ (JEP 320), הסרה של מחלקות כלי עזר פנימיות מדור קודם ואכיפה של אנקפסולציה מודולרית חזקה ‏ (JEP 403).

בגלל השינויים האלה, יכול להיות שיהיו שיבושים בשדרוג לגרסה 4.54.00 בשרתי proxy ל-API עם כללי מדיניות JavaCallout בהתאמה אישית או קובצי JAR של משאבים בהתאמה אישית (שמאוחסנים ברמת ה-proxy, הסביבה או הארגון).

קטגוריות של שינויים שעשויים להשפיע על קריאות ל-Java

  1. הוסרו באופן סופי מודולים של Java EE ו-CORBA (JEP 320): מודולים שנבנו בעבר בזמן הריצה של Java 8 (כולל JAXB javax.xml.bind.*,‏ JAF javax.activation.*,‏ JAX-WS javax.xml.ws.* ו-CORBA org.omg.*) הוסרו מ-Java SE. ההפניות לחבילות האלה בלי חבילות חלופיות עצמאיות נכשלות בזמן הריצה עם NoClassDefFoundError.
  2. הוסרו מחלקות של כלי עזר פנימיים: הוסרו רכיבי עזר פנימיים מדור קודם, כמו sun.misc.BASE64Encoder ו-sun.misc.BASE64Decoder. קריאות ל-callout שמפעילות את המחלקות האלה נכשלות עם השגיאה NoClassDefFoundError.
  3. הצפנה חזקה של רכיבים פנימיים ב-Java‏ (JEP 403): אי אפשר לגשת לחבילות פנימיות ב-java.base (כמו sun.security.*,‏ sun.reflect.* ו-com.sun.*) באופן רפלקטיבי מתוך קריאות מותאמות אישית. קריאות רפלקטיביות נכשלות בזמן הריצה עם InaccessibleObjectException.
  4. שינויים והסרות של חתימות של שיטות במחלקות Java שנותרו: במודולים מסוימים של Java, המחלקה נשארת ב-Java 21, אבל בנאים או חתימות של שיטות ספציפיות הוסרו, הוצאו משימוש או שונו (למשל, שיטות ספציפיות לניתוח DOM ב-org.w3c.dom.Document ובמחלקות קשורות לניתוח XML).

    זיהוי באמצעות כלים: הכלי לזיהוי שינויים מסמן הפניות למחלקות האלה בקטגוריה METHOD_SIGNATURE_MODIFICATION עם MEDIUM ודאות השפעה, ומבקש מהמפתחים לבדוק את קוד המקור של ה-callout שלהם כדי לזהות קריאות ל-method ששונו.

אסטרטגיות לתיקון שגיאות

לפני השדרוג, חשוב לוודא שכללי המדיניות של קריאה ל-Java ומשאבי ה-JAR בהתאמה אישית תואמים לסביבת זמן הריצה של Java 21. כלי זיהוי השינויים יעזור לכם לזהות את שרתי ה-proxy ל-API, התהליכים המשותפים ומשאבי ה-JAR של הסביבה או הארגון שמושפעים באשכול.

אסטרטגיות התיקון שמתוארות בקטע הזה הן הנחיות כלליות, ואפשר להשתמש בהן ביחד. בהתאם לדרישות התפעוליות שלכם, אתם יכולים לשלב בין אסטרטגיות שונות. לדוגמה, אפשר להשתמש באסטרטגיה 2 כדי לעדכן את קוד המקור של ה-callout, ובאסטרטגיה 3ב כדי לפרוס את עדכוני ה-proxy, וכך להשיג אפס זמן השבתה במהלך שדרוגי מעבד ההודעות.

אסטרטגיות 3A, ‏ 3B ו-3C הן שלוש דרכים ליישם את אותה גישה תפעולית: שדרוג הצומת ופריסה מחדש של ה-proxy בזמנים שונים, בלי לשנות את חבילת ה-proxy. בוחרים אחת מהאפשרויות האלה או שילוב שלהן בהתאם לדרישות הזמינות של ה-API.

כדי לבחור את הגישה המתאימה ביותר לפריסה, כדאי לעיין במדריך הבא:

מדריך לקבלת החלטות לגבי צמצום הסיכונים של קריאות ל-Java:

צריך לעדכן את חבילת ה-proxy ולפרוס אותה מחדש? תרחיש או דרישה שיטה מומלצת מה הבעיה שהיא פותרת מגבלות עיקריות
כן (עדכון החבילה בלבד) יש ספרייה עם תאימות כפולה; נדרש אפס זמן השבתה אסטרטגיה 1: שרת proxy עם תאימות כפולה באמצעות קובצי JAR מקובצים שחזור ספריות חסרות בגרסאות שונות ללא זמן השבתה נדרשת ספרייה עצמאית עם תאימות כפולה שתהיה זמינה ותפעיל את conf_system_java.21.enable.external.allowed.packages=true בגרסה 4.54.00
כן (שינוי קוד המקור) קוד המקור מתוחזק; נדרש תיקון נקי לטווח ארוך אסטרטגיה 2: הטמעה חלופית (מודרניזציה של קוד ותלות) פתרון קבוע של בעיות שקשורות להסרה של מחלקות ותלות פנימית ב-API צריך לשנות את קוד המקור ולפרוס מחדש (בשילוב עם אסטרטגיה 3A או 3B להשקה)
לא (גישה תפעולית) חלון זמן מותר לתחזוקה מתוזמנת אסטרטגיה 3א: זמן השבתה לפעילות תחזוקה מתוכננת (פריסה מחדש במקום) מאפשר לשדרג את הצומת קודם, ואז לפרוס את ה-proxy המעודכן נדרש זמן השבתה מתוזמן לצרכני API
לא (גישה תפעולית) אין צורך בזמן השבתה, אי אפשר לאגד קובצי JAR כפולים אסטרטגיה 3ב': יצירת סביבה חדשה (העברה ללא זמן השבתה) מבודד צמתים 4.53 ו-4.54 במהלך מיגרציה ללא שיבוש בתנועה צריך להשיג צומתי מעבד בקשות זמניים
לא (גישה תפעולית) אי אפשר לשנות חבילות של שרתי proxy לפני השדרוג * אסטרטגיה 3ג': מיקום של ספרייה חיצונית ברמת הצומת מספק קובצי JAR חסרים של ספריות בכל הצומת בלי לערוך חבילות של שרתי proxy משותף לכל שרתי ה-Proxy בצומת; לא פותר בעיות של השתקפות או חבילות java.*
לא (ספריות של צד שלישי בקוד סגור) ספריות של ספקי צד שלישי שמשתמשות ברפלקציה בנתונים פנימיים של Java ‫* אסטרטגיה 4: דגלים של JVM ‏ (--add-opens / --add-exports) הגדרת הרשאות פחות מחמירות להגבלות על השתקפות (reflection) בחבילות Java פנימיות אי אפשר לשחזר מחלקות או שיטות שהוסרו. חל על כל הצומת

שיטה 1: שרת proxy עם תאימות כפולה באמצעות חבילות JAR (מומלץ לבצע בדיקה לפני השדרוג כדי למנוע השבתה)

מתי כדאי להשתמש בשיטה הזו: כדאי להשתמש בשיטה הזו כש:

  • יש ספרייה חלופית עצמאית עם תאימות כפולה: יש קובץ JAR חלופי שמטמיע את הפונקציונליות הנדרשת ואפשר לצרף אותו ישירות ל-proxy ל-API בלי לשנות את קוד המקור.
  • אתם רוצים שה-proxies ל-API וה-קריאות ל-Java הקיימים שלכם יפעלו בצורה חלקה גם בגרסה הנוכחית (לדוגמה, Edge for Private Cloud 4.53.01) וגם בגרסה המשודרגת (Edge for Private Cloud 4.54.00).
  • לפני שמשדרגים את אשכול Edge for Private Cloud, כדאי לבדוק ולאמת את כל השינויים בסביבות ה-staging והייצור כדי לוודא שלא יהיו בעיות בלתי צפויות או זמני השבתה בתנועה בזמן אמת.
  • אתם רוצים להימנע מכתיבה מחדש או משינוי מבנה הקוד (refactoring) של הלוגיקה העסקית של הקריאה ל-Java.

איך זה עובד: ב-Java 8, ספריות מסוימות (כמו JAXB javax.xml.bind.* או Activation javax.activation.*) נבנו ישירות בסביבת זמן הריצה של Java 8. לכן, מפתחים לא צריכים לכלול קובצי JAR נוספים בחבילות ה-proxy שלהם. ב-Java 21, הספריות האלה הוסרו מסביבת זמן הריצה של Java.

כדי להפוך את שרת ה-proxy ל "תואם כפול" ב-Edge for Private Cloud בגרסאות 4.53.x ו-4.54.00:

  1. מזהים את הספרייה החסרה שנדרשת על ידי ה-callout (לדוגמה, JAXB או Activation).
  2. משיגים את קובץ ה-JAR החלופי העצמאי בקוד פתוח (לדוגמה, jakarta.xml.bind-api-2.3.3.jar ו-jaxb-runtime-2.3.8.jar).
  3. אפשר להציב את קובץ ה-JAR החלופי ישירות בחבילת ה-proxy בקטע apiproxy/resources/java/, או להעלות אותו לגרסת ה-proxy באמצעות Resource Files API ברמת ה-proxy, או להעלות אותו כקובץ משאבים ברמת הסביבה או ברמת הארגון. מידע נוסף על ניהול קובצי משאבים זמין במסמכי התיעוד של קובצי המשאבים של Apigee.
  4. פריסה ובדיקה לפני השדרוג: מעבדי בקשות ב-Edge for Private Cloud בגרסאות 4.53.x ו-4.54.00 טוענים מחלקות מקובצי ה-JAR המצורפים האלה. עכשיו אפשר לפרוס את חבילת ה-proxy המעודכנת הזו ולבדוק אותה באמצעות תנועה סינתטית באשכול הנוכחי של Edge for Private Cloud 4.53.x.
  5. הפעלת טעינה של חבילות מותרות חיצוניות במעבדי בקשות (נדרש לגרסה 4.54.00): כברירת מחדל ב-Edge for Private Cloud בגרסה 4.54.00, מושבתת (conf_system_java.21.enable.external.allowed.packages=false) טעינה של חבילות Java שהוסרו (כמו javax.xml.bind.* ו-javax.activation.*) מקובצי JAR של משאבים חיצוניים או משולבים, כך ששילוב קובצי ה-JAR לבד לא יעבוד כברירת מחדל. צריך להפעיל את המאפיין הזה ב-/opt/apigee/customer/application/message-processor.properties באמצעות קוד עם הגדרה (CwC) (אפשר להגדיר את המאפיין הזה לפני שמשדרגים את צומת מעבד ההודעות, או להגדיר אותו אחרי השדרוג ולהפעיל מחדש את מעבד ההודעות): 
    conf_system_java.21.enable.external.allowed.packages=true
  6. אפס בעיות בתנועה בשידור חי אחרי השדרוג: כשמשדרגים את האשכול ל-Edge for Private Cloud 4.54.00 עם conf_system_java.21.enable.external.allowed.packages=true מופעל, למעבד ההודעות כבר יש את קובץ ה-JAR הנדרש והוא טוען את המחלקות מקובץ המשאבים המצורף ללא כשל (NoClassDefFoundError), וכך מבטיח שדרוג חלק ללא השבתה.

דוגמת קוד: קריאה לאימות ולניתוח של הזמנת XML

נניח שיש לכם קריאה ל-Java טיפוסית של Apigee שמחלצת ומאמתת הזמנות בפורמט XML באמצעות JAXB (JAXBContext ו-Unmarshaller).

  • לפני התיקון (הפעולה נכשלת ב-Edge for Private Cloud 4.54.00): ב-Edge for Private Cloud 4.53.x, חבילת ה-proxy מכילה רק את קובץ ה-JAR של callout, והיא מסתמכת על ספריות זמן ריצה מובנות של Java 8 עבור JAXB: 
    apiproxy/
  resources/
    java/
      OrderXmlParserCallout.jar   <-- No JAXB JAR bundled

    הטמעה של קריאה ל-Java:

    package com.example.callout;

// other required imports
import java.io.StringReader;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.Unmarshaller;

public class OrderXmlParserCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        try {
            String requestXml = messageContext.getMessage().getContent();
            JAXBContext jaxbContext = JAXBContext.newInstance(Order.class);
            Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
            Order order = (Order) unmarshaller.unmarshal(new StringReader(requestXml));
            messageContext.setVariable("order_id", order.getId());
            return ExecutionResult.SUCCESS;
        } catch (Exception e) { }
    }
}

    הכשל: ב-Edge for Private Cloud 4.53.x, הפקודה הזו מופעלת ללא בעיה. אחרי שמשדרגים את הצומת ל-Edge for Private Cloud 4.54.00, ה-proxy הזה נכשל מיד במהלך עיבוד הבקשה:

    java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext
        at com.example.callout.OrderXmlParserCallout.execute(OrderXmlParserCallout.java:20)
  • אחרי התיקון (תאימות כפולה ב-Edge for Private Cloud 4.53.x וב-4.54.00): אין צורך לכתוב מחדש או לקמפל מחדש את קוד קריאה ל-Java. כדי להפוך את ה-proxy שלכם לתואם ישירות לשתי הגרסאות, אתם יכולים לספק את קובצי ה-JAR העצמאיים:
    1. לארוז או להעלות ישירות את קובצי ה-JAR העצמאיים: משיגים את ספריות ה-JAXB העצמאיות (jakarta.xml.bind-api-2.3.3.jar ו-jaxb-runtime-2.3.8.jar) וממקמים אותן בתוך חבילת ה-proxy בנתיב apiproxy/resources/java/: 
      apiproxy/
  resources/
    java/
      OrderXmlParserCallout.jar
      jakarta.xml.bind-api-2.3.3.jar
      jaxb-runtime-2.3.8.jar

      לחלופין, אפשר להעלות את jakarta.xml.bind-api-2.3.3.jar ו-jaxb-runtime-2.3.8.jar כקובצי משאבים באמצעות Resource Files API ברמת שרת ה-proxy, או ברמת הסביבה או ברמת הארגון, כדי שכל שרתי ה-proxy באותו היקף יוכלו לשתף אותם בלי לארוז אותם בכל חבילת proxy נפרדת.

      אם אתם יוצרים את חבילת ה-proxy מהמקור באמצעות Maven, הצהירו על יחסי התלות האלה ב-pom.xml כדי שהם ייארזו באופן אוטומטי במהלך ה-build.

    2. פריסה ובדיקה באשכול הנוכחי 4.53.x: פורסים את חבילת ה-proxy המעודכנת בסביבת Edge for Private Cloud 4.53.x הקיימת ושולחים שיחות בדיקה. מכיוון שמעבדי הבקשות של Edge for Private Cloud 4.53.x טוענים מחלקות מקובצי ה-JAR האלה, אתם יכולים לוודא שה-callout ממשיך לפעול באופן זהה.
    3. הפעלת טעינה של חבילות חיצוניות מותרות באמצעות CwC: כברירת מחדל, טעינה של חבילות חיצוניות מותרות מושבתת ב-Edge for Private Cloud 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false). צריך להפעיל אותה בכל צומת של מעבד בקשות ב-/opt/apigee/customer/application/message-processor.properties באמצעות קוד עם הגדרה (CwC): 
      conf_system_java.21.enable.external.allowed.packages=true
    4. אחרי השדרוג לא יהיו בעיות בתנועה בזמן אמת: אחרי שתאמתו את השרת בסביבה של גרסה 4.53.x ותגדירו אותו עם מאפיין CwC, השרת יהיה מוכן לחלוטין. כשמשדרגים את האשכול ל-Edge for Private Cloud 4.54.00, מעבד הבקשות טוען את מחלקות ה-JAXB הכלולות, וכך מבטיח אפס שגיאות ואפס שיבושים בתנועה בזמן אמת.

אסטרטגיה 2: הטמעה חלופית (חידוש קוד ותלות)

מתי כדאי להשתמש: מומלץ לשימוש בבסיסי קוד פעילים שבהם קוד המקור של ה-proxy מתוחזק בקלות. זו הגישה הכי נקייה לטווח הארוך לתאימות ל-Java 21. הערה לגבי ההשקה: פריסת גרסאות משודרגות של שרתי proxy דורשת תיאום של מעבד הבקשות, לכן צריך לשלב את האסטרטגיה הזו עם אסטרטגיה 3א' (במהלך חלון זמן לתחזוקה מתוכנן) או עם אסטרטגיה 3ב' (כדי להשיג אפס זמן השבתה עם מעבדי בקשות מקבילים).

איך זה עובד: מחליפים את המחלקות הפנימיות של Java שהוסרו בממשקי API רשמיים וסטנדרטיים של Java SE או במקבילות עצמאיות בקוד פתוח, ומארזים את יחסי התלות הנדרשים של צד שלישי ישירות בתוך קובצי המשאבים או ה-POM של חבילת ה-proxy.

דוגמאות לקוד:

דוגמה 1: מודרניזציה של שיטות וקוד (החלפת כלי עזר פנימיים שהוסרו)

ב-Java 8, קריאות החוצה השתמשו לעיתים קרובות במחלקות שירות פנימיות כמו sun.misc.BASE64Encoder. בגרסאות מודרניות של Java, המחלקות האלה הוסרו, אבל ה-API הסטנדרטי של java.util.Base64 מספק תחליפים ישירים בלי לדרוש קובצי JAR של יחסי תלות חיצוניים:

  • לפני (הטמעה של Java 8 מדור קודם): 
    // Incompatible in Edge for Private Cloud 4.54.00: sun.misc package removed
import sun.misc.BASE64Encoder;
// other required imports

public class Base64EncodeCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        BASE64Encoder encoder = new BASE64Encoder();
        String encoded = encoder.encode("ApigeePayload".getBytes());
        messageContext.setVariable("encoded_data", encoded);
        return ExecutionResult.SUCCESS;
    }
}
  • אחרי (הטמעה שתואמת ל-Java 21): 
    // Fully compatible with Java 21: uses standard Java SE java.util.Base64 (no external JARs needed)
import java.util.Base64;
// other required imports

public class Base64EncodeCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        String encoded = Base64.getEncoder().encodeToString("ApigeePayload".getBytes());
        messageContext.setVariable("encoded_data", encoded);
        return ExecutionResult.SUCCESS;
    }
}
דוגמה 2: ארגון קוד מחדש ברמת הייבוא עם ספרייה מקובצת (JAXB Namespace Prefix Mapper)

ב-Java 8, שרתי proxy ל-API שמתאימים אישית קידומות של מרחבי שמות ב-XML הרחיבו בדרך כלל את ממפה ה-JAXB הפנימי של Sun,‏ com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. ב-Java 21, חבילות Sun פנימיות מוסרות ואי אפשר לגשת אליהן.

הספרייה העצמאית בקוד פתוח (org.glassfish.jaxb:jaxb-runtime) מספקת את אותה מחלקה בקטע com.sun.xml.bind.marshaller.NamespacePrefixMapper. כל החתימות, הפרמטרים וסוגי ההחזרה של השיטות זהים – השינוי בקוד הוא רק בהצהרת הייבוא:

  • לפני (הטמעה של Java 8 מדור קודם): 
    // In Java 8: Relied on internal Sun class in Java 8 runtime
import com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper;
public class CustomNamespaceMapper extends NamespacePrefixMapper {
    @Override
    public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
        if ("http://schemas.example.com/orders".equals(namespaceUri)) {
            return "ord";
        }
        return suggestion;
    }
}
  • אחרי (הטמעה שתואמת ל-Java 21): 
    // In Java 21: Identical methods and logic; ONLY the import statement changes (".internal." removed)
import com.sun.xml.bind.marshaller.NamespacePrefixMapper;
public class CustomNamespaceMapper extends NamespacePrefixMapper {
    @Override
    public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
        if ("http://schemas.example.com/orders".equals(namespaceUri)) {
            return "ord";
        }
        return suggestion;
    }
}
  • הגדרת תלות בחבילה (pom.xml): כדי לספק את המחלקה הזו בזמן הריצה, צריך לכלול את ספריות ה-JAXB העצמאיות בתוך apiproxy/resources/java/ או להצהיר עליהן ב-pom.xml: 
    <dependencies>
    <!-- Standalone JAXB API for Java 21 -->
    <dependency>
        <groupId>jakarta.xml.bind</groupId>
        <artifactId>jakarta.xml.bind-api</artifactId>
        <version>2.3.3</version>
    </dependency>
    <!-- Standalone JAXB Runtime providing com.sun.xml.bind.marshaller.NamespacePrefixMapper -->
    <dependency>
        <groupId>org.glassfish.jaxb</groupId>
        <artifactId>jaxb-runtime</artifactId>
        <version>2.3.8</version>
    </dependency>
</dependencies>

אסטרטגיה 3א: זמן השבתה מתוכנן לצורך תחזוקה (פריסה מחדש במקום)

מתי להשתמש: מומלץ לסביבות עם חלונות זמן מתוזמנים לתחזוקה תפעולית, שבהן הפסקה קצרה בשירות היא מקובלת.

התהליך:

  1. לתאם חלון זמן לתחזוקה מתוזמנת עם צרכני ה-API.
  2. משדרגים את הרכיבים של Edge for Private Cloud לגרסה 4.54.00 לפי המדריך לדרכי שדרוג.
  3. פורסים את הגרסה המהודרת מראש של ה-proxy ל-API, שמתאימה לגרסה 4.54.00, באמצעות ממשק המשתמש החדש של Edge או Apigee Management API (Deployment (פריסה)).
  4. כדי לוודא שההודעה נשלחה, שולחים בקשות בדיקה סינתטיות למעבדי הבקשות ובודקים את היומנים באמצעות הכלי Trace.
  5. סוגרים את חלון הזמן לתחזוקה ופותחים מחדש את התנועה הציבורית.

שיטה 3ב: יצירת סביבה חדשה (העברה ללא השבתה)

מתי כדאי להשתמש: מומלץ לסביבות ייצור קריטיות שנדרשת בהן זמינות מלאה. משתמשים באפשרות הזו אם אי אפשר לעדכן את רכיב ה-Java Callout כך שיפעל גם ב-Java 8 וגם ב-Java 21 בו-זמנית.

איך זה עובד: באסטרטגיה הזו רוכשים סביבה חדשה אחת או יותר, כדי שתוכלו לחבר אליה צמתים של מעבדי בקשות בגרסאות שונות. לאחר מכן, פורסים שרתי proxy שתואמים ל-Java 8 בסביבה שמחוברת למעבדי בקשות בגרסה 4.53.X, ושרתי proxy שתואמים ל-Java 21 בסביבה שמחוברת למעבדי בקשות בגרסה 4.54.00. לאחר מכן, משתמשים במאזן עומסים או בשיטות ניתוב אחרות כדי לנתב את התנועה רק לשרת ה-proxy שתואם ל-Java 21.

כדי להשתמש באסטרטגיה הזו, חשוב להבין איך ארגונים, סביבות ומעבדי בקשות פועלים יחד כדי לבצע מעבר חד למערכת אחרת (cutover) ללא זמן השבתה (למידע נוסף, ראו מבנה הארגון של Apigee Edge):

  • ארגון ב-Apigee הוא גבול אדמיניסטרטיבי ברמה העליונה שמכיל כמה סביבות (לדוגמה, prod, test).
  • גרסה של proxy ל-API נפרסת בסביבה ספציפית. רק מעבדי ההודעות שמקושרים באופן מפורש לסביבה הזו נטענים ומבצעים את הגרסה של ה-proxy.
+------------------------------------------------------------------------+
|                          Apigee Organization                           |
|                                                                        |
|  Existing Environment (prod)            Temporary Env (prod-migration) |
|  +--------------------------------+     +----------------------------+ |
|  | Current 4.53.01 MP Nodes       |     | New 4.54.00 MP Nodes       | |
|  |               |                |     |              |             | |
|  | Proxy Rev N (4.53.01)          |     | Proxy Rev N+1 (Modernized) | |
|  +--------------------------------+     +----------------------------+ |
+------------------------------------------------------------------------+
                   ^                                    ^
                   | Step 1: Normal Live                | Step 2: Canary
                   |         Traffic (prod)             | Step 3: Complete
          +------------------------------------------------------+
          |       Upstream Load Balancer / Ingress Router        |
          +------------------------------------------------------+

הליך:

  1. יצירת סביבה זמנית: יוצרים סביבה חדשה (לדוגמה, prod-migration) בארגון (בהתאם להוראות במאמר הגדרת מארחים וסביבות וירטואליים) עם מארח וירטואלי ויציאה ייעודיים.
  2. הקצאת צומתי מעבד בקשות בגרסה 4.54.00: מתקינים את Edge for Private Cloud בגרסה 4.54.00 במכונות וירטואליות חדשות או זמניות, ומקשרים את הצמתים האלה אל prod-migration (ראו הוספת מעבד בקשות).
  3. זיהוי שרתי ה-proxy המושפעים ויצירת גרסאות מעודכנות: מזהים שרתי proxy ל-API שמשתמשים בקריאות ל-Java (באמצעות הכלי לזיהוי שינויים) ויוצרים גרסה חדשה של כל שרת proxy מושפע עם קריאות ל-Java שתואמות ל-Edge for Private Cloud 4.54.00 (באמצעות אסטרטגיה 1 או אסטרטגיה 2).
  4. פריסת גרסאות מעודכנות של שרת ה-proxy בסביבה הזמנית: פריסת הגרסאות המעודכנות והתואמות של שרת ה-proxy באופן בלעדי ב-prod-migration.
  5. אימות והעברת תנועה: מריצים בדיקות אימות סינתטיות במארח הווירטואלי החדש. אחרי האימות, מגדירים את מאזן העומסים החיצוני (F5, ‏ NGINX) כך שיפנה את תנועת הלקוחות מ-prod אל prod-migration.
  6. שדרוג הצמתים המקוריים וחזרה אליהם: מבטלים את הפריסה של שרתי ה-proxy הקודמים מ-prod. משדרגים את הצמתים המקוריים של מעבד בקשות לגרסה 4.54.00 לפי המדריך לדרכי שדרוג. פורסים את הגרסאות המעודכנות של ה-proxy אל prod, מפנים את תעבורת הנתונים של מאזן העומסים בחזרה אל prod ומאמתים את הפעולה.
  7. הוצאה משימוש של הסביבה הזמנית: מבטלים את הפריסה של שרתי ה-proxy מ-prod-migration, מסירים את הצמתים הזמניים של מעבד הבקשות ומוחקים את הסביבה הזמנית.

שיטה 3C: מיקום של ספריות חיצוניות ברמת הצומת (ספריות משותפות של חזרה למצב הקודם)

מתי להשתמש: מומלץ להשתמש באפשרות הזו אם יש לכם כמה שרתי proxy ל-API שמסתמכים על מחלקות Java שהוסרו ב-Java 21, ואין לכם אפשרות לקמפל מחדש או לארוז מחדש כל חבילת proxy בנפרד לפני השדרוג.

איך זה עובד: ב-Edge for Private Cloud 4.54.00, מעבדי הבקשות מספקים מנגנון לטעינת מחלקות Java חסרות מספריית צומת ייעודית: $APIGEE_ROOT/data/edge-message-processor/external-lib.

כשהמנגנון הזה מופעל, מעבד הבקשות בודק אם יש מחלקות חסרות בספרייה הזו לפני שהוא חוזר לרזולוציית ברירת המחדל. אפשר לספק את המחלקות החסרות על ידי אחזור שלהן מקובצי JAR של ספריות צד שלישי, או על ידי אריזת המחלקות הנדרשות בקובץ JAR והצבתן ב-external-lib.

התהליך:

  1. יוצרים את ספריית ה-JAR החיצונית בכל צומת של מעבד בקשות: 
    mkdir -p /opt/apigee/data/edge-message-processor/external-lib
  2. ממקמים את קובצי ה-JAR הנדרשים בספרייה: מעתיקים את קובצי ה-JAR שמכילים את המחלקות הנדרשות אל /opt/apigee/data/edge-message-processor/external-lib.
  3. הגדרת הרשאות מתאימות לקובץ: מוודאים שלמשתמש השירות apigee יש הרשאות קריאה: 
    chown -R apigee:apigee /opt/apigee/data/edge-message-processor/external-lib
chmod 755 /opt/apigee/data/edge-message-processor/external-lib
chmod 644 /opt/apigee/data/edge-message-processor/external-lib/*.jar
  4. הפעלת טעינת חבילות חיצוניות בהגדרות של מעבד הבקשות: כברירת מחדל ב-Edge for Private Cloud 4.54.00, טעינת חבילות חיצוניות מותרות מושבתת (conf_system_java.21.enable.external.allowed.packages=false). כדי לאפשר למעבד הבקשות לפתור ולטעון מחלקות מ-/opt/apigee/data/edge-message-processor/external-lib, צריך להפעיל את המאפיין הזה ב-/opt/apigee/customer/application/message-processor.properties באמצעות קוד עם הגדרה (CwC): 
    conf_system_java.21.enable.external.allowed.packages=true
  5. מפעילים מחדש את המעבד של ההודעות: 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

אסטרטגיה 4: דגלי JVM ‏ (--add-opens / --add-exports – שימוש זהיר ורק כמוצא אחרון)

מתי להשתמש: השתמשו באסטרטגיה הזו כמוצא אחרון לספריות של ספקים חיצוניים בקוד סגור שבהן קוד המקור לא זמין, הספקים לא פרסמו עדכונים ל-Java 21 וקובץ ה-JAR תלוי אך ורק בגישה רפלקטיבית לחבילות Java פנימיות.

התהליך:

  1. מזהים את החבילה הלא נגישה שמשמשת לרפלקציה: מזהים את המודול והחבילה הפנימיים של Java שספריית הצד השלישי ניגשת אליהם באמצעות רפלקציה. הערה: שגיאות ההשתקפות האלה מתרחשות רק ב-Java 21 ב-Edge for Private Cloud 4.54.00, ולא יופיעו ביומנים של גרסה 4.53.x. בודקים את היומנים של מעבד בקשות (/opt/apigee/var/log/edge-message-processor/system.log) אחרי השדרוג כדי למצוא את InaccessibleObjectException שמזהה את המודול והחבילה הנדרשים: 
    java.lang.reflect.InaccessibleObjectException: Unable to make field private final byte[] java.lang.String.value accessible: module java.base does not "opens java.lang" to unnamed module
  2. עורכים את /opt/apigee/customer/application/message-processor.properties באמצעות קוד עם הגדרה (CwC) (יוצרים את הקובץ אם הוא לא קיים).
  3. מוסיפים את הדגלים המטורגטים --add-opens או --add-exports אל bin_setenv_ext_jvm_opts. 
    # Configure targeted JVM module access for closed-source legacy callouts (enclosed in double quotes)
bin_setenv_ext_jvm_opts="-XX:+UseG1GC -XX:+AlwaysPreTouch --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/sun.misc=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED --add-opens java.base/sun.security.x509=ALL-UNNAMED"
  4. מוודאים שיש בעלות והרשאות מתאימות לקובץ: 
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
chmod 644 /opt/apigee/customer/application/message-processor.properties
  5. מפעילים מחדש את מעבד ההודעות באמצעות apigee-service: 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

שינויים ב-TLS ובסט האלגוריתמים להצפנה (cipher suite)

ב-Edge for Private Cloud 4.54.00, רכיבי הפלטפורמה העיקריים – כולל מעבד הבקשות, שרת הניהול והנתב – מעודכנים כך שיפעלו ב-Java 21 LTS. העדכון הזה משפר את האבטחה הקריפטוגרפית על ידי הפעלת TLS 1.3 כברירת מחדל (JEP 332). מעבדי הבקשות מנהלים עכשיו משא ומתן על TLS 1.3 כפרוטוקול המועדף לחיבורים לקצה העורפי, וחוזרים ל-TLS 1.2 אם הקצה העורפי לא תומך בו.

דרישות לגבי קצה עורפי מדור קודם ופתרון בעיות

קו הבסיס הקריפטוגרפי של Java 21 מעדכן את רשימת הפרוטוקולים וסט האלגוריתמים להצפנה (cipher suite) שמושבתים כברירת מחדל ב-jdk.tls.disabledAlgorithms (כמו פרוטוקולי TLS מדור קודם וסטים של אלגוריתמים להצפנה (cipher suite) סטטיים של מפתחות RSA ללא סודיות העברה: TLS_RSA_*). מכיוון שאתם מספקים סביבת זמן ריצה משלכם של Java 21, הרשימה המדויקת של הפרוטוקולים וסט האלגוריתמים להצפנה (cipher suite) המושבתים תלויה בהטמעה הספציפית של Java 21.

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

  • עדכון האבטחה של ה-Backend (מומלץ): שדרוג שרתי היעד ומאזני העומסים כדי לתמוך ב-TLS 1.2 או ב-TLS 1.3 עם סטי אלגוריתמים להצפנה מודרניים של ECDHE. כדי להגדיר פרוטוקולים וסטים של אלגוריתמים להצפנה (cipher suite) בשרתי ה-proxy ל-API, קראו את המאמר הגדרת TLS מ-Edge לקצה העורפי ואת חומר העזר בנושא הגדרת TargetEndpoint של TLS/SSL (או את המאמר איזון עומסים בין שרתי בק-אנד אם אתם משתמשים ב-TargetServers).
  • הפעלה מחדש של אלגוריתמים מדור קודם באמצעות CwC (אמצעי מעבר במהלך השדרוג): אם אי אפשר להשלים את השדרוגים של הקצה העורפי לפני שדרוג הפלטפורמה, אפשר להפעיל מחדש באופן זמני את האלגוריתמים הנדרשים באמצעות קוד עם הגדרה (CwC):
    1. בודקים את ערך ברירת המחדל של jdk.tls.disabledAlgorithms בהתקנה של Java 21 (לדוגמה, ב-$JAVA_HOME/conf/security/java.security).
    2. צריך לשנות את הערך של conf_jvmsecurity_jdk.tls.disabledAlgorithms ב-/opt/apigee/customer/application/message-processor.properties לאותה רשימה של אלגוריתמים מושבתים, ולהסיר רק את הרשומה TLS_RSA_* (להשאיר את כל שאר האלגוריתמים המושבתים ללא שינוי כדי שההגנות שנותרו יישארו מופעלות).
    3. מפעילים מחדש את מעבד הבקשות באמצעות apigee-service. אחרי שהקצה העורפי יתמוך בסט אלגוריתמים להצפנה מסוג ECDHE, צריך להסיר את שינוי ברירת המחדל הזה.
  • עדכון רשימת היתרים מותאמת אישית של סט אלגוריתמים להצפנה: אם ביטלתם בעבר את conf_http_HTTPTransport.ssl.cipher.suites.whitelist, בדקו אותה לפני השדרוג. ב-Java 21 אין יותר תמיכה בסטים הסטטיים של אלגוריתמים להצפנה מסוג RSA ‏ (TLS_RSA_*), ולכן רשימת היתרים שמכילה רק את הסטים האלה משאירה את מעבד הבקשות בלי אלגוריתם הצפנה שמיש, והקריאות לקצה העורפי נכשלות עם השגיאה no cipher suites in common. צריך להסיר את הרשומות של TLS_RSA_* ולהגדיר סטים מודרניים של אלגוריתמים להצפנה (cipher suite) שנתמכים בהטמעה של Java 21. אם לא ביטלתם את ברירת המחדל של המאפיין הזה, חבילות השירות הנתמכות כבר כלולות בברירות המחדל של גרסה 4.54.00, ולא צריך לבצע שינויים.
  • עדכון של סטי אלגוריתמים להצפנה פנימיים של הנתב למעבד הבקשות: אם בעבר שיניתם את conf_message-processor-communication_local.http.ssl.ciphers באמצעות סטי אלגוריתמים להצפנה RSA סטטיים, לפני השדרוג צריך לעדכן אותו באמצעות סטי אלגוריתמים להצפנה מודרניים שנתמכים על ידי הטמעת Java 21. אחרת, הנתב לא יוכל להשלים לחיצת יד בפרוטוקול TLS עם מעבד הבקשות. אחר כך מפעילים מחדש את מעבד ההודעות: 
    apigee-service edge-message-processor restart
     אפשר לעיין במאמר הגדרת TLS בין נתב לבין מעבד בקשות.

לפרטים על הגדרת TLS בין רכיבי Edge, ראו הגדרת TLS בין נתב לבין מעבד בקשות.

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

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

הכלי מזהה גורמים פוטנציאליים שעלולים לחסום את השדרוג – כולל ספריות לא תואמות ל-Java 21, ממשקי API פנימיים עם הצפנה חזקה, הוצאה משימוש של מדיניות מדור קודם ומגבלות RDN של OpenLDAP – ומפיק דוחות עם המלצות לפעולה שיעזרו לכם לבחור אסטרטגיות מתאימות לתיקון הבעיות.

כדי לקבל מידע מלא על דרישות מוקדמות, הוראות להורדה, תחביר של שורת הפקודה ודוחות לדוגמה, אפשר לעיין במדריך הייעודי לכלי לזיהוי שינויים.