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

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

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

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

שלוש יכולות שזמינות בגרסה 4.53.01 לא נתמכות ב-Edge for Private Cloud 4.54.00. לפני שמתכננים את השדרוג, כדאי לעיין בתכונות שלא נתמכות בגרסה 4.54.00.

תכונות שלא נתמכות בגרסה 4.54.00

גרסה 4.54.00 של Edge for Private Cloud לא תומכת ביכולות הבאות, שזמינות בגרסה 4.53.01. אם אתם משתמשים באחת מהן, אל תשדרגו לגרסה 4.54.00. להישאר בגרסה 4.53.01 ולפנות לתמיכה של Apigee.

  • התקנה ב-Google Distributed Cloud (GDC) במודל Air-gapped. גרסה 4.54.00 של Edge for Private Cloud לא מאושרת לסביבות GDC עם air gap. כדי לראות את התהליך בגרסה 4.53.01, קראו את המאמר התקנת Apigee ב-Google Distributed Cloud במודל Air-gapped.
  • ‫RHEL 8.X או Rocky 8.X עם FIPS. בגרסה 4.54.00 של Edge for Private Cloud אין תמיכה בהתקנה במארח RHEL 8.X או Rocky 8.X עם FIPS. מערכות ההפעלה האלה נתמכות כשמצב FIPS לא מופעל. בנושאי ההגדרות של גרסה 4.54.00 גם לא מופיעה ההנחיה הספציפית ל-FIPS שמופיעה בגרסה 4.53.01, כולל הכנת מאגר מפתחות BCFKS, מאפיין ההגדרה השקטה FIPS_OS והגדרת מאגר מפתחות PKCS12. להנחיות לגבי גרסה 4.53.01, קראו את המאמר Edge for Private Cloud ב-RHEL 8.X או ב-Rocky 8.X עם תמיכה ב-FIPS.
  • שילוב של מודול אבטחה לחומרה (HSM) דרומה. בגרסה 4.54.00 של Edge for Private Cloud אין תמיכה בחיבורי TLS דרומה ממעבדי בקשות לשירותי יעד בקצה העורפי שמשתמשים ב-HSM ברשת Entrust nShield. לגבי ההליך בגרסה 4.53.01, ראו מדריך לשילוב מודול אבטחת חומרה (HSM) דרומה ב-Apigee Edge for Private Cloud.

שינויים במדיניות בנושא קריאה ל-Java

ב-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.*) באופן רפלקטיבי מ-callouts בהתאמה אישית. קריאות רפלקטיביות נכשלות בזמן הריצה עם 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 של הסביבה או הארגון שמושפעים באשכול.

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

אסטרטגיות 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 במהלך ההעברה, בלי להפריע לתנועה צריך להשיג צומתי מעבד בקשות זמניים
לא (גישה תפעולית) אי אפשר לשנות חבילות פרוקסי לפני השדרוג * אסטרטגיה 3ג': מיקום של ספרייה חיצונית ברמת הצומת מספק קובצי JAR חסרים של ספריות בכל הצומת בלי לערוך חבילות של שרתי proxy משותף לכל שרתי ה-Proxy בצומת; לא פותר בעיות של השתקפות או חבילות java.*
לא (ספריות של צד שלישי בקוד סגור) ספריות של ספקים חיצוניים שמשתמשות ברפלקציה על רכיבים פנימיים של Java * אסטרטגיה 4: דגלי JVM‏ (‎--add-opens / --add-exports) הגדרת הרשאות פחות מחמירות להגבלות על השתקפות (reflection) בחבילות Java פנימיות אי אפשר לשחזר מחלקות או שיטות שהוסרו. חל על כל הצומת

אסטרטגיה 1: פרוקסי עם תאימות כפולה באמצעות קובצי 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. פורסים את הגרסה שעברה הידור מראש ותואמת ל-4.54.00 של שרת ה-proxy ל-API באמצעות ממשק המשתמש של New Edge או Apigee Management API (פריסות).
  4. כדי לוודא שההודעה נשלחה, שולחים בקשות בדיקה סינתטיות למעבדי הבקשות ובודקים את היומנים באמצעות הכלי Trace.
  5. סוגרים את חלון הזמן לתחזוקה ופותחים מחדש את התנועה הציבורית.

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

מתי כדאי להשתמש: מומלץ לסביבות ייצור קריטיות שדורשות אפס זמן השבתה. השתמשו באפשרות הזו אם אי אפשר לעדכן את הקריאה ל-Java כך שתפעל ב-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, מסירים את הצמתים הזמניים של מעבד הבקשות ומוחקים את הסביבה הזמנית.

אסטרטגיה 3ג': מיקום של ספרייה חיצונית ברמת הצומת (ספריות משותפות חלופיות)

מתי להשתמש: מומלץ להשתמש באפשרות הזו אם יש לכם כמה שרתי 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 סטטיים, כדאי לבצע את הפעולות הבאות:

  • לשדרג את אבטחת הקצה העורפי (מומלץ): שדרגו את שרתי היעד ומאזני העומסים כך שיתמכו ב-TLS 1.2 או ב-TLS 1.3 עם סט אלגוריתמים להצפנה (cipher suite) מסוג 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. אחרי שה-backend יתמוך בסט אלגוריתמים להצפנה מסוג 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, ומפיק דוחות פרקטיים שיעזרו לכם לבחור אסטרטגיות מתאימות לתיקון.

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