Änderungen in Edge for Private Cloud 4.54.00

Änderungen im Überblick

In Edge for Private Cloud 4.54.00 wurden mehrere Änderungen eingeführt, die die Sicherheit der Plattform verbessern. Außerdem wurden Plattformkomponenten aktualisiert, damit sie mit Java 21 ausgeführt werden. Zwei der folgenden Abschnitte befassen sich mit diesen Änderungen:

• Änderungen an der JavaCallout-Richtlinie
• Änderungen an TLS und Cipher Suites

Zusätzlich zu diesen Änderungen sollten Sie sich den speziellen Leitfaden zum Tool für die Änderungserkennung ansehen. Dieses Dienstprogramm wurde zur Verfügung gestellt, um Änderungen an Proxys, freigegebenen Abläufen oder anderen Artefakten in Ihrem Cluster zu identifizieren, die aufgrund dieses Upgrades zu Störungen führen können.

Änderungen an der JavaCallout-Richtlinie

In Edge for Private Cloud 4.54.00 werden die Kernkomponenten der Plattform, einschließlich Message Processor, Management Server und Router, aktualisiert, um auf Java 21 LTS ausgeführt zu werden. Java 21 modernisiert die Java-Plattform. Dazu gehören das Entfernen von Legacy-Java EE- und CORBA-Modulen (JEP 320), das Entfernen von Legacy-internen Hilfsklassen und das Erzwingen einer starken modularen Kapselung (JEP 403).

Aufgrund dieser Änderungen kann es bei API-Proxys mit benutzerdefinierten JavaCallout-Richtlinien oder benutzerdefinierten Ressourcen-JARs (auf Proxy-, Umgebungs- oder Organisationsebene gespeichert) beim Upgrade auf Version 4.54.00 zu Störungen kommen.

Kategorien von Änderungen, die sich auf Java-Callouts auswirken können

1. Java EE- und CORBA-Module dauerhaft entfernt (JEP 320): Module, die zuvor in die Java 8-Laufzeitumgebung integriert waren (einschließlich JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.* und CORBA org.omg.*), wurden aus Java SE entfernt. Callouts, die auf diese Pakete verweisen, ohne eigenständige Ersatzpakete zu bündeln, schlagen zur Laufzeit mit NoClassDefFoundError fehl.
2. Interne Hilfsklassen entfernt:Ältere interne Hilfsprogramme wie sun.misc.BASE64Encoder und sun.misc.BASE64Decoder wurden entfernt. Callouts, die diese Klassen aufrufen, schlagen mit NoClassDefFoundError fehl.
3. Starke Kapselung von Java-Interna (JEP 403): Auf interne Pakete in java.base (z. B. sun.security.*, sun.reflect.* und com.sun.*) kann nicht über benutzerdefinierte Callouts zugegriffen werden. Reflektive Aufrufe schlagen zur Laufzeit mit InaccessibleObjectException fehl.
4. Änderungen und Entfernungen von Methodensignaturen in verbleibenden Java-Klassen: In bestimmten Java-Modulen ist die Klasse in Java 21 weiterhin vorhanden, aber bestimmte Konstruktoren oder Methodensignaturen wurden entfernt, eingestellt oder geändert (z. B. bestimmte DOM-Parsing-Methoden in org.w3c.dom.Document und zugehörige XML-Parsing-Klassen).

   Toolerkennung: Das Tool zur Änderungserkennung kennzeichnet Verweise auf diese Klassen in der Kategorie METHOD_SIGNATURE_MODIFICATION mit MEDIUM Auswirkungsgewissheit. Entwickler werden dann aufgefordert, den Quellcode ihrer Callouts auf geänderte Methodenaufrufe zu prüfen.

Strategien zur Abhilfe

Prüfen Sie vor dem Upgrade, ob Ihre Java Callout-Richtlinien und benutzerdefinierten JAR-Ressourcen mit der Java 21-Laufzeitumgebung kompatibel sind. Mit dem Tool zur Änderungserkennung können Sie betroffene API-Proxys, freigegebene Abläufe und JAR-Ressourcen für Umgebung oder Organisation in Ihrem Cluster identifizieren.

Die in diesem Abschnitt beschriebenen Abhilfestrategien sind allgemeine Leitfäden und schließen sich nicht gegenseitig aus. Je nach Ihren betrieblichen Anforderungen können Sie Strategien kombinieren. Sie können beispielsweise den Quellcode von Callouts mit Strategie 2 modernisieren und die aktualisierten Proxy-Überarbeitungen mit Strategie 3B bereitstellen, um während der Message Processor-Upgrades keine Ausfallzeiten zu haben.

Die Strategien 3A, 3B und 3C sind drei Möglichkeiten, denselben operativen Ansatz umzusetzen: den Knoten aktualisieren und den Proxy zu unterschiedlichen Zeiten neu bereitstellen, ohne das Proxy-Bundle zu ändern. Wählen Sie eine oder eine Kombination dieser Optionen aus, je nach Ihren Anforderungen an die API-Verfügbarkeit.

In der folgenden Entscheidungshilfe finden Sie den am besten geeigneten Ansatz für Ihre Bereitstellung:

Entscheidungshilfe für Java-Callout-Gegenmaßnahmen:

Strategie 1: Dual-kompatibler Proxy über gebündelte JARs (Test vor dem Upgrade für null Ausfallzeit)

Wann sollte diese Strategie verwendet werden? Verwenden Sie diese Strategie, wenn:

• Eine dual-kompatible eigenständige Ersatzbibliothek ist verfügbar: Es gibt eine Ersatz-JAR-Datei, die die erforderliche Funktionalität implementiert und direkt in Ihren API-Proxy eingebunden werden kann, ohne dass Änderungen am Quellcode erforderlich sind.
• Sie möchten, dass Ihre vorhandenen API-Proxys und Java-Callouts sowohl in Ihrer aktuellen Version (z. B. Edge for Private Cloud 4.53.01) als auch in der aktualisierten Version (Edge for Private Cloud 4.54.00) nahtlos funktionieren.
• Sie möchten alle Änderungen in Ihren Staging- und Produktionsumgebungen testen und überprüfen, bevor Sie Ihren Edge for Private Cloud-Cluster aktualisieren. So vermeiden Sie unerwartete Probleme und Ausfallzeiten bei Live-Traffic.
• Sie möchten die Geschäftslogik Ihres Java-Callout nicht neu schreiben oder refaktorieren.

Funktionsweise: In Java 8 waren bestimmte Bibliotheken (z. B. JAXB javax.xml.bind.* oder Activation javax.activation.*) direkt in die Java 8-Laufzeit integriert. Aus diesem Grund mussten Entwickler keine zusätzlichen JAR-Dateien in ihre Proxy-Bundles einfügen. In Java 21 wurden diese Bibliotheken aus der Java-Laufzeit entfernt.

So machen Sie Ihren Proxy für Edge for Private Cloud 4.53.x und 4.54.00 „dual-kompatibel“:

1. Ermitteln Sie die fehlende Bibliothek, die für den Callout erforderlich ist (z. B. JAXB oder Activation).
2. Laden Sie die eigenständige Open-Source-JAR-Datei herunter (z. B. jakarta.xml.bind-api-2.3.3.jar und jaxb-runtime-2.3.8.jar).
3. Legen Sie die Ersatz-JAR-Datei entweder direkt im Proxy-Bundle unter apiproxy/resources/java/ ab, laden Sie sie mit der Resource Files API auf Proxy-Ebene in die Proxy-Überarbeitung hoch oder laden Sie sie als Ressourcendatei auf Umgebungsebene oder Organisationsebene hoch. Weitere Informationen zum Verwalten von Ressourcendateien finden Sie in der Dokumentation zu Apigee-Ressourcendateien.
4. Vor dem Upgrade bereitstellen und testen:Message Processors in Edge for Private Cloud 4.53.x und 4.54.00 laden Klassen aus diesen gebündelten JARs. Sie können dieses aktualisierte Proxy-Bundle jetzt bereitstellen und mit synthetischem Traffic in Ihrem aktuellen Edge for Private Cloud 4.53.x-Cluster testen.
5. Laden externer zulässiger Pakete auf Message Processors aktivieren (erforderlich für 4.54.00): Standardmäßig ist in Edge for Private Cloud 4.54.00 das Laden entfernter Java-Pakete (wie javax.xml.bind.* und javax.activation.*) aus externen oder gebündelten Ressourcen-JARs deaktiviert (conf_system_java.21.enable.external.allowed.packages=false). Daher funktioniert das Bündeln der JARs allein standardmäßig nicht. Sie müssen dieses Attribut in /opt/apigee/customer/application/message-processor.properties mit Code mit Konfiguration (CwC) aktivieren. Sie können dieses Attribut vor dem Upgrade des Message Processor-Knotens konfigurieren oder nach dem Upgrade festlegen und den Message Processor neu starten:

   conf_system_java.21.enable.external.allowed.packages=true

6. Keine Probleme mit Live-Traffic nach dem Upgrade: Wenn Ihr Cluster anschließend auf Edge for Private Cloud 4.54.00 mit aktiviertem conf_system_java.21.enable.external.allowed.packages=true aktualisiert wird, ist die erforderliche JAR-Datei bereits im Message Processor verfügbar und die Klassen werden ohne Fehler aus der gebündelten Ressourcendatei geladen (NoClassDefFoundError). Das sorgt für ein reibungsloses Upgrade ohne Ausfallzeiten.

Codebeispiel: XML-Bestätigung und Parsing-Callout für Bestellungen

Betrachten Sie einen typischen Apigee-Java-Callout, der eingehende XML-Bestellungen mit JAXB (JAXBContext und Unmarshaller) extrahiert und validiert.

• Vor dem Fix (Fehler in Edge for Private Cloud 4.54.00): In Edge for Private Cloud 4.53.x enthält das Proxy-Bundle nur die Callout-JAR-Datei. Für JAXB werden die integrierten Java 8-Laufzeitbibliotheken verwendet:

  apiproxy/
    resources/
      java/
        OrderXmlParserCallout.jar   <-- No JAXB JAR bundled

  Die Java-Callout-Implementierung:

  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) { }
      }
  }

  Der Fehler:In Edge for Private Cloud 4.53.x wird dies ohne Probleme ausgeführt. Sobald der Knoten auf Edge for Private Cloud 4.54.00 aktualisiert wurde, schlägt dieser Proxy bei der Anfrageverarbeitung sofort fehl:

  java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext
          at com.example.callout.OrderXmlParserCallout.execute(OrderXmlParserCallout.java:20)

• Nach der Fehlerbehebung (Dual-kompatibel für Edge for Private Cloud 4.53.x und 4.54.00): Sie müssen Ihren Java-Callout-Code nicht neu schreiben oder neu kompilieren. Sie können Ihren Proxy direkt dual-kompatibel machen, indem Sie die eigenständigen JAR-Dateien bereitstellen:
  1. Eigenständige JARs direkt bündeln oder hochladen: Rufen Sie die eigenständigen JAXB-Bibliotheken (jakarta.xml.bind-api-2.3.3.jar und jaxb-runtime-2.3.8.jar) ab und platzieren Sie sie in Ihrem Proxy-Bundle unter apiproxy/resources/java/:

     apiproxy/
       resources/
         java/
           OrderXmlParserCallout.jar
           jakarta.xml.bind-api-2.3.3.jar
           jaxb-runtime-2.3.8.jar

     Alternativ können Sie jakarta.xml.bind-api-2.3.3.jar und jaxb-runtime-2.3.8.jar als Ressourcendateien mit der Resource Files API auf Proxy-Ebene oder auf Umgebungsebene oder Organisationsebene hochladen, damit alle Proxys im selben Bereich sie gemeinsam nutzen können, ohne sie in jedem einzelnen Proxy-Bundle zu bündeln.

     Wenn Sie Ihr Proxy-Bundle mit Maven aus dem Quellcode erstellen, deklarieren Sie diese Abhängigkeiten in Ihrer pom.xml, damit sie während des Builds automatisch verpackt werden.

  2. Im aktuellen 4.53.x-Cluster bereitstellen und testen:Stellen Sie das aktualisierte Proxy-Bundle in Ihrer vorhandenen Edge for Private Cloud-Umgebung (Version 4.53.x) bereit und senden Sie Testaufrufe. Da Edge for Private Cloud 4.53.x-Message Processors Klassen aus diesen gebündelten JAR-Dateien laden, können Sie prüfen, ob der Callout weiterhin identisch funktioniert.
  3. Laden externer zulässiger Pakete über CwC aktivieren: Da das Laden externer zulässiger Pakete in Edge for Private Cloud 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false) standardmäßig deaktiviert ist, aktivieren Sie es auf jedem Message Processor-Knoten in /opt/apigee/customer/application/message-processor.properties mit Code mit Konfiguration (CwC):

     conf_system_java.21.enable.external.allowed.packages=true

  4. Keine Probleme mit Live-Traffic nach dem Upgrade:Wenn Ihr Proxy in Ihrer 4.53.x-Umgebung validiert und mit der CwC-Property konfiguriert wurde, ist er vollständig vorbereitet. Wenn Sie Ihren Cluster auf Edge for Private Cloud 4.54.00 aktualisieren, lädt der Message Processor die gebündelten JAXB-Klassen, sodass keine Fehler auftreten und der Live-Traffic nicht unterbrochen wird.

Strategie 2: Alternative Implementierung (Modernisierung von Code und Abhängigkeiten)

Anwendungsfälle: Empfohlen für aktive Codebasen, in denen der Proxy-Quellcode leicht verwaltet werden kann. Dies ist der sauberste langfristige Ansatz für die Java 21-Compliance. Hinweis zum Roll-out: Da für die Bereitstellung modernisierter Proxy-Überarbeitungen eine Message Processor-Koordination erforderlich ist, sollten Sie diese Strategie mit Strategie 3A (während eines geplanten Wartungsfensters) oder Strategie 3B (um mit parallelen Message Processors keine Ausfallzeiten zu erreichen) kombinieren.

So funktioniert es: Ersetzen Sie entfernte interne Java-Klassen durch offizielle Standard-Java-SE-APIs oder eigenständige Open-Source-Äquivalente und verpacken Sie erforderliche Drittanbieterabhängigkeiten direkt in den Ressourcendateien oder der POM Ihres Proxy-Bundles.

Codebeispiele:

Beispiel 1: Methoden- und Codemodernisierung (Ersetzen entfernter interner Dienstprogramme)

In Java 8 wurden in Callouts häufig interne Dienstprogrammklassen wie sun.misc.BASE64Encoder verwendet. In modernen Java-Versionen wurden diese Klassen entfernt, aber die Standard-java.util.Base64-API bietet direkten Ersatz, ohne dass externe JAR-Abhängigkeiten erforderlich sind:

• Vorher (Legacy-Java 8-Implementierung):

  // 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;
      }
  }

• Nachher (Java 21-konforme Implementierung):

  // 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;
      }
  }

Beispiel 2: Refaktorierung auf Importebene mit gebündelter Bibliothek (JAXB Namespace Prefix Mapper)

In Java 8 haben API-Proxys, die XML-Namespace-Präfixe anpassen, häufig den internen JAXB-Mapper com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper von Sun erweitert. In Java 21 werden interne Sun-Pakete entfernt und sind nicht mehr zugänglich.

Die eigenständige Open-Source-Bibliothek (org.glassfish.jaxb:jaxb-runtime) stellt die identische Klasse unter com.sun.xml.bind.marshaller.NamespacePrefixMapper bereit. Alle Methodensignaturen, Parameter und Rückgabetypen sind identisch. Die Codeänderung betrifft ausschließlich die Importanweisung:

• Vorher (Legacy-Java 8-Implementierung):

  // 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;
      }
  }

• Nachher (Java 21-kompatible Implementierung):

  // 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;
      }
  }

• Konfiguration der gebündelten Abhängigkeiten (pom.xml): Wenn Sie diese Klasse zur Laufzeit bereitstellen möchten, bündeln Sie die eigenständigen JAXB-Bibliotheken in apiproxy/resources/java/ oder deklarieren Sie sie in Ihrer 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>

Strategie 3A: Geplante Wartungsausfallzeit (In-Place-Bereitstellung)

Wann verwenden? Empfohlen für Umgebungen mit geplanten Wartungsfenstern, in denen eine kurze Dienstunterbrechung akzeptabel ist.

Vorgehensweise:

1. Koordinieren Sie ein geplantes Wartungsfenster mit API-Nutzern.
2. Führen Sie ein Upgrade Ihrer Edge for Private Cloud-Komponenten auf Version 4.54.00 durch. Folgen Sie dazu der Anleitung zu Upgradepfaden.
3. Stellen Sie die vorkompilierte, mit Version 4.54.00 kompatible Überarbeitung Ihres API-Proxys über die New Edge-Benutzeroberfläche oder die Apigee Management API (Deployments) bereit.
4. Prüfen Sie die Ausführung von Callouts, indem Sie synthetische Testanfragen an die Message Processors senden und die Logs mit dem Trace-Tool untersuchen.
5. Schließen Sie das Wartungsfenster und öffnen Sie den öffentlichen Traffic wieder.

Strategie 3B: Neue Umgebung erstellen (Migration ohne Ausfallzeiten)

Anwendungsbereiche:Empfohlen für geschäftskritische Produktionsumgebungen, die keine Ausfallzeiten zulassen. Verwenden Sie diese Option, wenn Ihr Java-Callout nicht so aktualisiert werden kann, dass es sowohl mit Java 8 als auch mit Java 21 funktioniert.

Funktionsweise: Bei dieser Strategie werden eine oder mehrere neue Umgebungen beschafft, damit Sie Message Processor-Knoten verschiedener Versionen damit verbinden können. Stellen Sie anschließend Java 8-kompatible Proxys in der Umgebung bereit, die mit Message Processors der Version 4.53.X verbunden ist, und Java 21-kompatible Proxys in der Umgebung, die mit Message Processors der Version 4.54.00 verbunden ist. Verwenden Sie dann einen Load Balancer oder andere Routing-Techniken, um Traffic nur an den mit Java 21 kompatiblen Proxy weiterzuleiten.

Für diese Strategie ist es wichtig, zu verstehen, wie Organisationen, Umgebungen und Message Processors interagieren, um eine Umstellung ohne Ausfallzeiten zu ermöglichen. Weitere Informationen finden Sie unter Apigee Edge-Organisationsstruktur:

• Eine Apigee-Organisation ist eine übergeordnete administrative Grenze, die mehrere Umgebungen enthält (z. B. prod, test).
• Eine API-Proxy-Version wird in einer bestimmten Umgebung bereitgestellt. Nur die Message Processors, die explizit an diese Umgebung gebunden sind, laden die Proxy-Überarbeitung und führen sie aus.

+------------------------------------------------------------------------+
|                          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        |
          +------------------------------------------------------+

Vorgehensweise:

1. Temporäre Umgebung erstellen:Erstellen Sie in Ihrer Organisation eine neue Umgebung (z. B. prod-migration) mit einem dedizierten virtuellen Host und Port (siehe Virtuelle Hosts und Umgebungen einrichten).
2. Message Processor-Knoten der Version 4.54.00 bereitstellen:Installieren Sie Edge for Private Cloud 4.54.00 auf neuen oder temporären VM-Instanzen und binden Sie diese Knoten an prod-migration (siehe Message Processor hinzufügen).
3. Betroffene Proxys identifizieren und aktualisierte Überarbeitungen erstellen: Identifizieren Sie API-Proxys, die Java-Callouts verwenden (mit dem Tool zur Änderungserkennung), und erstellen Sie eine neue Überarbeitung jedes betroffenen Proxys mit Java-Callouts, die mit Edge for Private Cloud 4.54.00 kompatibel sind (mit Strategie 1 oder Strategie 2).
4. Modernisierte Proxy-Versionen in der temporären Umgebung bereitstellen: Stellen Sie die aktualisierten, kompatiblen Proxy-Versionen ausschließlich in prod-migration bereit.
5. Traffic prüfen und verschieben: Führen Sie synthetische Verifizierungstests für den neuen virtuellen Host aus. Konfigurieren Sie nach der Überprüfung Ihren externen Load Balancer (F5, NGINX) so, dass der Client-Traffic von prod an prod-migration weitergeleitet wird.
6. Originalknoten aktualisieren und zurückwechseln:Heben Sie die Bereitstellung der alten Proxys in prod auf. Führen Sie ein Upgrade der ursprünglichen Message Processor-Knoten auf Version 4.54.00 durch. Folgen Sie dazu der Anleitung zu Upgradepfaden. Stellen Sie die modernisierten Proxy-Überarbeitungen in prod bereit, leiten Sie den Load-Balancer-Traffic zurück zu prod und prüfen Sie den Vorgang.
7. Temporäre Umgebung außer Betrieb nehmen:Heben Sie die Bereitstellung von Proxys in prod-migration auf, entfernen Sie die temporären Message Processor-Knoten und löschen Sie die temporäre Umgebung.

Strategie 3C: Platzierung externer Bibliotheken auf Knotenebene (gemeinsam genutzte Fallback-Bibliotheken)

Verwendung: Empfohlen, wenn Sie mehrere API-Proxys haben, die auf Java-Klassen basieren, die in Java 21 entfernt wurden, und das Neukompilieren oder Neupacken jedes einzelnen Proxy-Bundles vor dem Upgrade betrieblich nicht möglich ist.

Funktionsweise: In Edge for Private Cloud 4.54.00 bieten Message Processors einen Mechanismus zum Laden fehlender Java-Klassen aus einem dedizierten Knotenverzeichnis: $APIGEE_ROOT/data/edge-message-processor/external-lib.

Wenn dieser Mechanismus aktiviert ist, sucht der Message Processor in diesem Verzeichnis nach fehlenden Klassen, bevor er auf die Standardauflösung zurückgreift. Sie können die fehlenden Klassen aus JARs von Drittanbieterbibliotheken beziehen oder die erforderlichen Klassen in einem JAR bündeln und in external-lib platzieren.

Vorgehensweise:

1. Erstellen Sie das Verzeichnis für die externe Bibliothek auf jedem Message Processor-Knoten:

   mkdir -p /opt/apigee/data/edge-message-processor/external-lib

2. Erforderliche JAR-Dateien in das Verzeichnis einfügen:Kopieren Sie die JAR-Dateien mit den erforderlichen Klassen in /opt/apigee/data/edge-message-processor/external-lib.
3. Legen Sie die entsprechenden Dateiberechtigungen fest: Der Dienstnutzer apigee muss Leseberechtigungen haben:

   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. Laden externer Pakete in der Message Processor-Konfiguration aktivieren: Standardmäßig ist in Edge for Private Cloud 4.54.00 das Laden externer zulässiger Pakete deaktiviert (conf_system_java.21.enable.external.allowed.packages=false). Damit der Message Processor Klassen aus /opt/apigee/data/edge-message-processor/external-lib auflösen und laden kann, müssen Sie dieses Attribut in /opt/apigee/customer/application/message-processor.properties mit Code with Config (CwC) aktivieren:

   conf_system_java.21.enable.external.allowed.packages=true

5. Starten Sie den Message Processor neu:

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Strategie 4: JVM-Flags (--add-opens / --add-exports – Vorsicht und letzter Ausweg)

Wann verwenden:Verwenden Sie diese Strategie als letzten Ausweg für Drittanbieterbibliotheken mit geschlossenem Quellcode, bei denen der Quellcode nicht verfügbar ist, Anbieter keine Java 21-Updates veröffentlicht haben und die JAR-Datei streng von reflektierendem Zugriff auf interne Java-Pakete abhängt.

Vorgehensweise:

1. Nicht zugängliches Paket identifizieren, das für die Reflexion verwendet wird: Ermitteln Sie das interne Java-Modul und -Paket, auf das Ihre Drittanbieterbibliothek reflexiv zugreift. Hinweis: Diese Reflexionsfehler treten ausschließlich unter Java 21 in Edge for Private Cloud 4.54.00 auf und werden nicht in den Logs der Version 4.53.x angezeigt. Prüfen Sie nach dem Upgrade die Message Processor-Logs (/opt/apigee/var/log/edge-message-processor/system.log) auf die InaccessibleObjectException, die das erforderliche Modul und Paket identifiziert:

   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. Bearbeiten Sie /opt/apigee/customer/application/message-processor.properties mit Code with Config (CwC) (erstellen Sie die Datei, falls sie nicht vorhanden ist).
3. Hängen Sie die gewünschten Flags --add-opens oder --add-exports an bin_setenv_ext_jvm_opts an.

   # 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. Achten Sie auf die richtigen Dateieigentümer und Berechtigungen:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
   chmod 644 /opt/apigee/customer/application/message-processor.properties

5. Starten Sie den Message Processor mit apigee-service neu:

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Änderungen bei TLS und Cipher Suites

In Edge for Private Cloud 4.54.00 werden die Kernkomponenten der Plattform, einschließlich Message Processor, Management Server und Router, aktualisiert, um auf Java 21 LTS ausgeführt zu werden. Mit diesem Update wird die kryptografische Sicherheit modernisiert, indem TLS 1.3 standardmäßig aktiviert wird (JEP 332). Message Processors handeln jetzt TLS 1.3 als bevorzugtes Protokoll für ausgehende Backend-Verbindungen aus und greifen auf TLS 1.2 zurück, wenn das Backend TLS 1.3 nicht unterstützt.

Legacy-Backend-Anforderungen und ‑Korrekturmaßnahmen

Mit der kryptografischen Baseline von Java 21 wird die Liste der standardmäßig in jdk.tls.disabledAlgorithms deaktivierten Protokolle und Cipher Suites aktualisiert (z. B. Legacy-TLS-Protokolle und statische RSA-Schlüsselaustausch-Suites ohne Forward Secrecy: TLS_RSA_*). Da Sie Ihre eigene Java 21-Laufzeit bereitstellen, hängt die genaue Liste der deaktivierten Protokolle und Cipher Suites von Ihrer spezifischen Java 21-Implementierung ab.

Wenn Ihre vorhandenen API-Proxys mit einer Legacy-Backend-Infrastruktur verbunden sind, die deaktivierte Protokolle oder statische RSA-Chiffren erfordert, prüfen Sie die folgenden Aktionen:

• Backend-Sicherheit modernisieren (empfohlen): Aktualisieren Sie Zielserver und Load Balancer, um TLS 1.2 oder TLS 1.3 mit modernen ECDHE-Cipher-Suites zu unterstützen. Informationen zum Konfigurieren von Protokollen und Cipher Suites in Ihren API-Proxys finden Sie unter TLS von Edge zum Backend konfigurieren und in der Referenz zur TLS/SSL-TargetEndpoint-Konfiguration (oder unter Load-Balancing auf Backend-Servern, wenn Sie TargetServers verwenden).
• Ältere Algorithmen mit CwC wieder aktivieren (Übergangsmaßnahme während des Upgrades): Wenn Backend-Upgrades nicht vor dem Plattform-Upgrade abgeschlossen werden können, können Sie erforderliche Algorithmen vorübergehend mit Code with Config (CwC) wieder aktivieren:
  1. Prüfen Sie den Standardwert für jdk.tls.disabledAlgorithms in Ihrer Java 21-Installation (z. B. in $JAVA_HOME/conf/security/java.security).
  2. Überschreiben Sie conf_jvmsecurity_jdk.tls.disabledAlgorithms in /opt/apigee/customer/application/message-processor.properties mit derselben Liste deaktivierter Algorithmen und entfernen Sie nur den Eintrag TLS_RSA_*. Lassen Sie alle anderen deaktivierten Algorithmen unverändert, damit die verbleibenden Schutzmaßnahmen aktiviert bleiben.
  3. Starten Sie den Message Processor mit apigee-service neu. Entfernen Sie diese Überschreibung, sobald das Backend ECDHE-Cipher Suites unterstützt.
• Benutzerdefinierte Zulassungsliste für Cipher Suites aktualisieren: Wenn Sie conf_http_HTTPTransport.ssl.cipher.suites.whitelist zuvor überschrieben haben, überprüfen Sie die Liste vor dem Upgrade. Java 21 unterstützt die statischen RSA-Suites (TLS_RSA_*) nicht mehr. Wenn eine Zulassungsliste nur diese Suites enthält, hat der Message Processor keine nutzbare Verschlüsselung und Backend-Aufrufe schlagen mit no cipher suites in common fehl. Entfernen Sie die TLS_RSA_*-Einträge und konfigurieren Sie moderne Cipher Suites, die von Ihrer Java 21-Implementierung unterstützt werden. Wenn Sie dieses Attribut nicht überschrieben haben, enthalten die Standardwerte von 4.54.00 bereits die unterstützten Suites und es ist keine Änderung erforderlich.
• Interne Router-zu-Message Processor-Chiffren aktualisieren: Wenn Sie conf_message-processor-communication_local.http.ssl.ciphers zuvor mit statischen RSA-Suites überschrieben haben, aktualisieren Sie sie vor dem Upgrade mit modernen Chiffren-Suites, die von Ihrer Java 21-Implementierung unterstützt werden. Andernfalls kann der Router keinen TLS-Handshake mit dem Message Processor durchführen. Starten Sie dann den Message Processor neu:

  apigee-service edge-message-processor restart

  Weitere Informationen finden Sie unter TLS zwischen einem Router und einem Message Processor konfigurieren.

Weitere Informationen zum Konfigurieren von TLS zwischen Edge-Komponenten finden Sie unter TLS zwischen einem Router und einem Message Processor konfigurieren.

Tool zur Änderungserkennung

Apigee bietet ein Tool zur Änderungserkennung, mit dem Sie Ihren Cluster nach bereitgestellten API-Proxys, Richtlinien, freigegebenen Abläufen und Ressourcen-JARs durchsuchen können, die vom Upgrade auf Edge for Private Cloud 4.54.00 betroffen sein könnten.

Das Tool identifiziert potenzielle Upgrade-Blocker, darunter mit Java 21 inkompatible Bibliotheken, stark gekapselte interne APIs, veraltete Richtlinien und OpenLDAP-RDN-Limits, und erstellt Berichte mit umsetzbaren Empfehlungen, die Ihnen bei der Auswahl geeigneter Abhilfestrategien helfen.

Eine vollständige Liste der Voraussetzungen, eine Downloadanleitung, die Befehlszeilensyntax und Beispielberichte finden Sie im Leitfaden zum Tool zur Änderungserkennung.