Modifications apportées à Edge for Private Cloud 4.54.00

Présentation des modifications

Edge for Private Cloud 4.54.00 introduit plusieurs modifications qui améliorent la stratégie de sécurité de la plate-forme et met à jour les composants de la plate-forme pour qu'ils s'exécutent avec Java 21. Deux des sections ci-dessous traitent de ces modifications :

• Modifications apportées au règlement sur les appels Java
• Modifications apportées au protocole TLS et à la suite de chiffrement

En plus de ces modifications, consultez le guide dédié à l'outil de détection des modifications. Cet utilitaire a été mis à disposition pour identifier les modifications apportées aux proxys, aux flux partagés ou à d'autres artefacts de votre cluster qui pourraient entraîner des perturbations à la suite de cette mise à niveau.

Modifications apportées à la règle d'appel Java

Dans Edge for Private Cloud 4.54.00, les composants principaux de la plate-forme, y compris le processeur de messages, le serveur de gestion et le routeur, sont mis à jour pour s'exécuter sur Java 21 LTS. Java 21 modernise la plate-forme Java, ce qui inclut la suppression des anciens modules Java EE et CORBA (JEP 320), la suppression des anciennes classes d'utilitaires internes et l'application d'une encapsulation modulaire forte (JEP 403).

En raison de ces modifications, les proxys d'API avec des règles JavaCallout personnalisées ou des fichiers JAR de ressources personnalisés (stockés au niveau du proxy, de l'environnement ou de l'organisation) peuvent subir des perturbations lors de la mise à niveau vers la version 4.54.00.

Catégories de modifications pouvant avoir un impact sur les callouts Java

1. Suppression définitive des modules Java EE et CORBA (JEP 320) : les modules précédemment intégrés à l'environnement d'exécution Java 8 (y compris JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.* et CORBA org.omg.*) ont été supprimés de Java SE. Les appels faisant référence à ces packages sans regrouper les remplacements autonomes échouent au moment de l'exécution avec NoClassDefFoundError.
2. Suppression des classes d'utilitaires internes : les anciens assistants internes tels que sun.misc.BASE64Encoder et sun.misc.BASE64Decoder ont été supprimés. Les appels de ces classes échouent avec l'erreur NoClassDefFoundError.
3. Encapsulation forte des éléments internes de Java (JEP 403) : les packages internes de java.base (tels que sun.security.*, sun.reflect.* et com.sun.*) ne sont pas accessibles de manière réflexive à partir des callouts personnalisés. Les appels réflexifs échouent au moment de l'exécution avec InaccessibleObjectException.
4. Modifications et suppressions de signatures de méthode dans les classes Java survivantes : dans certains modules Java, la classe reste présente dans Java 21, mais des constructeurs ou des signatures de méthode spécifiques ont été supprimés, obsolètes ou modifiés (par exemple, des méthodes d'analyse DOM spécifiques dans org.w3c.dom.Document et les classes d'analyse XML associées).

   Détection par l'outil : l'outil de détection des modifications signale les références à ces classes dans la catégorie METHOD_SIGNATURE_MODIFICATION avec une certitude d'impact MEDIUM, ce qui invite les développeurs à inspecter le code source de leurs callouts pour identifier les appels de méthode modifiés.

Stratégies de correction

Avant de procéder à la mise à niveau, assurez-vous que vos règles JavaCallout et vos ressources JAR personnalisées sont compatibles avec l'environnement d'exécution Java 21. L'outil de détection des modifications vous aidera à identifier les proxys d'API, les flux partagés et les ressources JAR d'environnement ou d'organisation concernés dans votre cluster.

Les stratégies de correction décrites dans cette section sont des guides généraux et ne s'excluent pas mutuellement. En fonction de vos exigences opérationnelles, vous pouvez combiner des stratégies. Par exemple, vous pouvez moderniser le code source des appels à l'aide de la stratégie 2 et déployer les révisions de proxy mises à jour à l'aide de la stratégie 3B pour éviter tout temps d'arrêt lors des mises à niveau des processeurs de messages.

Les stratégies 3A, 3B et 3C sont trois façons de mettre en œuvre la même approche opérationnelle : mettre à niveau le nœud et redéployer le proxy à des moments différents, sans modifier le bundle de proxy. Choisissez l'une de ces options ou une combinaison de plusieurs d'entre elles en fonction de vos exigences de disponibilité des API.

Consultez le guide de décision suivant pour sélectionner l'approche la plus appropriée pour votre déploiement :

Guide de décision pour les corrections d'appel Java :

Stratégie 1 : Proxy à double compatibilité via des fichiers JAR groupés (testez avant la mise à niveau pour éviter tout temps d'arrêt)

Quand l'utiliser : utilisez cette stratégie lorsque :

• Une bibliothèque de remplacement autonome à double compatibilité est disponible : un fichier JAR de remplacement existe. Il implémente la fonctionnalité requise et peut être regroupé directement dans votre proxy d'API sans nécessiter de modifications du code source.
• Vous souhaitez que vos proxys d'API et vos appels Java existants fonctionnent de manière fluide à la fois sur votre version actuelle (par exemple, Edge for Private Cloud 4.53.01) et sur la version mise à niveau (Edge for Private Cloud 4.54.00).
• Vous souhaitez tester et vérifier toutes les modifications dans vos environnements de préproduction et de production avant de mettre à niveau votre cluster Edge for Private Cloud, afin d'éviter tout problème inattendu et tout temps d'arrêt du trafic en direct.
• Vous souhaitez éviter de réécrire ou de refactoriser la logique métier de votre appel Java.

Comment ça marche : dans Java 8, certaines bibliothèques (comme JAXB javax.xml.bind.* ou Activation javax.activation.*) étaient intégrées directement à l'environnement d'exécution Java 8. Les développeurs n'avaient donc pas besoin d'inclure de fichiers JAR supplémentaires dans leurs bundles de proxy. Dans Java 21, ces bibliothèques ont été supprimées de l'environnement d'exécution Java.

Pour rendre votre proxy "doublement compatible" avec Edge pour le cloud privé 4.53.x et 4.54.00 :

1. Identifiez la bibliothèque manquante requise par votre accroche (par exemple, JAXB ou Activation).
2. Obtenez le fichier JAR de remplacement Open Source autonome (par exemple, jakarta.xml.bind-api-2.3.3.jar et jaxb-runtime-2.3.8.jar).
3. Placez le fichier JAR de remplacement directement dans le bundle de proxy sous apiproxy/resources/java/, importez-le dans la révision du proxy à l'aide de l'API Resource Files au niveau du proxy, ou importez-le en tant que fichier de ressources au niveau de l'environnement ou au niveau de l'organisation. Pour en savoir plus sur la gestion des fichiers de ressources, consultez la documentation sur les fichiers de ressources Apigee.
4. Déployez et testez avant la mise à niveau : les processeurs de messages dans Edge pour Private Cloud 4.53.x et 4.54.00 chargent les classes à partir de ces fichiers JAR groupés. Vous pouvez déployer ce bundle de proxy mis à jour et le tester avec du trafic synthétique dans votre cluster Edge for Private Cloud 4.53.x actuel dès maintenant.
5. Activer le chargement des packages externes autorisés sur les processeurs de messages (obligatoire pour la version 4.54.00) : par défaut, dans Edge for Private Cloud 4.54.00, le chargement des packages Java supprimés (tels que javax.xml.bind.* et javax.activation.*) à partir de fichiers JAR de ressources externes ou groupés est désactivé (conf_system_java.21.enable.external.allowed.packages=false). Par conséquent, le regroupement des fichiers JAR seuls ne fonctionnera pas par défaut. Vous devez activer cette propriété dans /opt/apigee/customer/application/message-processor.properties à l'aide de code with config (CwC) (vous pouvez configurer cette propriété avant de mettre à niveau le nœud du processeur de messages, ou la définir après la mise à niveau et redémarrer le processeur de messages) :

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

6. Aucun problème de trafic en direct après la mise à niveau : lorsque votre cluster est ensuite mis à niveau vers Edge for Private Cloud 4.54.00 avec conf_system_java.21.enable.external.allowed.packages=true activé, le processeur de messages dispose déjà du fichier JAR requis et charge les classes à partir du fichier de ressources groupé sans échec (NoClassDefFoundError), ce qui garantit une mise à niveau fluide et sans temps d'arrêt.

Exemple de code : encadré d'appel pour la validation et l'analyse XML des commandes

Prenons l'exemple d'un appel Java Apigee standard qui extrait et valide les commandes XML entrantes à l'aide de JAXB (JAXBContext et Unmarshaller).

• Avant la correction (échec dans Edge pour le cloud privé 4.54.00) : dans Edge pour le cloud privé 4.53.x, le bundle de proxy ne contient que le fichier JAR d'appel, qui s'appuie sur les bibliothèques d'exécution Java 8 intégrées pour JAXB :

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

  L'implémentation de l'appel 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) { }
      }
  }

  Échec : dans Edge for Private Cloud 4.53.x, l'exécution se déroule sans problème. Une fois le nœud mis à niveau vers Edge for Private Cloud 4.54.00, ce proxy échoue immédiatement lors du traitement de la requête :

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

• Après la correction (double compatibilité avec Edge for Private Cloud 4.53.x et 4.54.00) : vous n'avez pas besoin de réécrire ni de recompiler votre code d'appel Java. Vous pouvez rendre votre proxy directement compatible avec les deux versions en fournissant les fichiers JAR autonomes :
  1. Regroupez ou importez directement les fichiers JAR autonomes : obtenez les bibliothèques JAXB autonomes (jakarta.xml.bind-api-2.3.3.jar et jaxb-runtime-2.3.8.jar), puis placez-les dans votre bundle de proxy sous apiproxy/resources/java/ :

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

     Vous pouvez également importer jakarta.xml.bind-api-2.3.3.jar et jaxb-runtime-2.3.8.jar en tant que fichiers de ressources à l'aide de l'API Fichiers de ressources au niveau du proxy, ou au niveau de l'environnement ou de l'l'organisation. Tous les proxys du même champ d'application pourront ainsi les partager sans les regrouper dans chaque bundle de proxy individuel.

     Si vous créez votre bundle de proxy à partir de la source à l'aide de Maven, déclarez ces dépendances dans votre pom.xml afin qu'elles soient empaquetées automatiquement lors de la création.

  2. Déployez et testez sur votre cluster 4.53.x actuel : déployez le bundle de proxys mis à jour dans votre environnement Edge for Private Cloud 4.53.x existant et envoyez des appels de test. Étant donné que les processeurs de messages Edge for Private Cloud 4.53.x chargent les classes à partir de ces fichiers JAR groupés, vous pouvez vérifier que le callout continue de fonctionner de la même manière.
  3. Activer le chargement des packages externes autorisés via CwC : comme le chargement des packages externes autorisés est désactivé par défaut dans Edge for Private Cloud 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false), activez-le sur chaque nœud de processeur de messages dans /opt/apigee/customer/application/message-processor.properties à l'aide du code avec configuration (CwC) :

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

  4. Aucun problème de trafic en direct après la mise à niveau : une fois validé dans votre environnement 4.53.x et configuré avec la propriété CwC, votre proxy est entièrement prêt. Lorsque vous mettez à niveau votre cluster vers Edge for Private Cloud 4.54.00, le processeur de messages charge les classes JAXB groupées, ce qui garantit zéro erreur et zéro interruption du trafic en temps réel.

Stratégie 2 : Implémentation alternative (modernisation du code et des dépendances)

Quand l'utiliser : recommandé pour les codebases actifs où le code source du proxy est facilement géré. Il s'agit de l'approche la plus propre à long terme pour la conformité avec Java 21. Remarque sur le déploiement : Étant donné que le déploiement de révisions de proxy modernisées nécessite la coordination du processeur de messages, associez cette stratégie à la stratégie 3A (pendant un intervalle de maintenance planifié) ou à la stratégie 3B (pour éviter tout temps d'arrêt avec des processeurs de messages parallèles).

Fonctionnement : remplacez les classes internes Java supprimées par des API Java SE standards officielles ou des équivalents autonomes Open Source, et empaquetez les dépendances tierces requises directement dans les fichiers de ressources ou le POM de votre groupe de proxys.

Exemples de code :

Exemple 1 : Modernisation de la méthode et du code (remplacement des utilitaires internes supprimés)

Dans Java 8, les encadrés utilisaient fréquemment des classes utilitaires internes telles que sun.misc.BASE64Encoder. Dans Java moderne, ces classes ont été supprimées, mais l'API java.util.Base64 standard fournit des remplacements directs sans nécessiter de fichiers JAR de dépendance externes :

• Avant (ancienne implémentation 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;
      }
  }

• Après (implémentation conforme à 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;
      }
  }

Exemple 2 : Refactorisation au niveau de l'importation avec une bibliothèque groupée (JAXB Namespace Prefix Mapper)

Dans Java 8, les proxys d'API personnalisant les préfixes d'espace de noms XML étendaient généralement le mappeur JAXB interne de Sun com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. Dans Java 21, les packages Sun internes sont supprimés et inaccessibles.

La bibliothèque Open Source autonome (org.glassfish.jaxb:jaxb-runtime) fournit la classe identique sous com.sun.xml.bind.marshaller.NamespacePrefixMapper. Toutes les signatures de méthode, tous les paramètres et tous les types renvoyés sont identiques. La modification du code se situe strictement au niveau de l'instruction d'importation :

• Avant (ancienne implémentation 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;
      }
  }

• Après (implémentation conforme à 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;
      }
  }

• Configuration des dépendances groupées (pom.xml) : pour fournir cette classe au moment de l'exécution, regroupez les bibliothèques JAXB autonomes dans apiproxy/resources/java/ ou déclarez-les dans votre 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>

Stratégie 3A : Temps d'arrêt pour maintenance planifiée (redéploiement sur place)

Quand l'utiliser : recommandé pour les environnements avec des intervalles de maintenance opérationnelle planifiés où une brève interruption de service est acceptable.

Procédure :

1. Coordonnez un intervalle de maintenance planifié avec les utilisateurs de l'API.
2. Mettez à niveau vos composants Edge for Private Cloud vers la version 4.54.00 en suivant le guide des chemins de mise à niveau.
3. Déployez la révision précompilée de votre proxy d'API compatible avec la version 4.54.00 à l'aide de la nouvelle UI Edge ou de l'API de gestion Apigee (Déploiements).
4. Vérifiez l'exécution des appels en envoyant des requêtes de test synthétiques aux processeurs de messages et en inspectant les journaux à l'aide de l'outil Trace.
5. Fermez la fenêtre de maintenance et rouvrez le trafic public.

Stratégie 3B : Créer un environnement (migration sans temps d'arrêt)

Quand l'utiliser : recommandé pour les environnements de production stratégiques nécessitant un temps d'arrêt nul. Utilisez cette option lorsque votre appel Java ne peut pas être mis à jour pour fonctionner simultanément sur Java 8 et Java 21.

Fonctionnement : cette stratégie consiste à acquérir un ou plusieurs nouveaux environnements afin de pouvoir y connecter des nœuds Message Processor de différentes versions. Déployez ensuite des proxys compatibles avec Java 8 dans l'environnement câblé avec des processeurs de messages 4.53.X et des proxys compatibles avec Java 21 dans l'environnement câblé avec des processeurs de messages 4.54.00. Utilisez ensuite un équilibreur de charge ou d'autres techniques de routage pour acheminer le trafic uniquement vers le proxy compatible avec Java 21.

Pour cette stratégie, il est essentiel de comprendre comment les organisations, les environnements et les processeurs de messages interagissent pour effectuer une transition sans temps d'arrêt (pour en savoir plus, consultez Structure de l'organisation Apigee Edge) :

• Une organisation Apigee est une limite administrative de niveau supérieur contenant plusieurs environnements (par exemple, prod, test).
• Une révision de proxy d'API est déployée dans un environnement spécifique. Seuls les processeurs de messages explicitement liés à cet environnement chargent et exécutent la révision du 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        |
          +------------------------------------------------------+

Procédure :

1. Créez un environnement temporaire : créez un environnement (par exemple, prod-migration) dans votre organisation (en suivant Configurer des hôtes et des environnements virtuels) avec un hôte et un port virtuels dédiés.
2. Provisionnez des nœuds Processeur de messages 4.54.00 : installez Edge for Private Cloud 4.54.00 sur des instances de VM nouvelles ou temporaires, puis associez ces nœuds à prod-migration (consultez Ajouter un Processeur de messages).
3. Identifier les proxys concernés et créer des révisions mises à jour : identifiez les proxys d'API utilisant des appels Java (à l'aide de l'outil de détection des modifications) et créez une révision de chaque proxy concerné avec des appels Java compatibles avec Edge for Private Cloud 4.54.00 (en appliquant la stratégie 1 ou la stratégie 2).
4. Déployer les révisions de proxy modernisées dans l'environnement temporaire : déployez les révisions de proxy mises à jour et compatibles exclusivement dans prod-migration.
5. Vérifier et déplacer le trafic : exécutez des tests de validation synthétiques sur le nouvel hôte virtuel. Une fois la vérification effectuée, configurez votre équilibreur de charge externe (F5, NGINX) pour rediriger le trafic client de prod vers prod-migration.
6. Mettre à niveau les nœuds d'origine et revenir en arrière : annulez le déploiement des anciens proxys de prod. Mettez à niveau les nœuds du processeur de messages d'origine vers la version 4.54.00 en suivant le guide des chemins de mise à niveau. Déployez les révisions de proxy modernisées sur prod, redirigez le trafic de l'équilibreur de charge vers prod et vérifiez le fonctionnement.
7. Mise hors service de l'environnement temporaire : annulez le déploiement des proxys de prod-migration, supprimez les nœuds de processeur de messages temporaires et supprimez l'environnement temporaire.

Stratégie 3C : Placement de bibliothèques externes au niveau des nœuds (bibliothèques de remplacement partagées)

Quand l'utiliser : recommandé lorsque vous disposez de plusieurs proxys d'API qui s'appuient sur des classes Java supprimées dans Java 21, et que la recompilation ou le reconditionnement de chaque groupe de proxys avant la mise à niveau n'est pas possible d'un point de vue opérationnel.

Fonctionnement : Dans Edge for Private Cloud 4.54.00, les processeurs de messages fournissent un mécanisme permettant de charger les classes Java manquantes à partir d'un répertoire de nœuds dédié : $APIGEE_ROOT/data/edge-message-processor/external-lib.

Lorsque ce mécanisme est activé, le processeur de messages vérifie si des classes sont manquantes dans ce répertoire avant de revenir à la résolution par défaut. Vous pouvez fournir les classes manquantes en les sourçant à partir de fichiers JAR de bibliothèques tierces ou en regroupant les classes requises dans un fichier JAR et en le plaçant dans external-lib.

Procédure :

1. Créez le répertoire de la bibliothèque externe sur chaque nœud du processeur de messages :

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

2. Placez les fichiers JAR requis dans le répertoire : copiez les fichiers JAR contenant les classes requises dans /opt/apigee/data/edge-message-processor/external-lib.
3. Définissez les autorisations de fichier appropriées : assurez-vous que l'utilisateur du service apigee dispose des autorisations de lecture :

   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. Activez le chargement de packages externes dans la configuration du processeur de messages : par défaut dans Edge for Private Cloud 4.54.00, le chargement de packages autorisés externes est désactivé (conf_system_java.21.enable.external.allowed.packages=false). Pour permettre au processeur de messages de résoudre et de charger des classes à partir de /opt/apigee/data/edge-message-processor/external-lib, vous devez activer cette propriété dans /opt/apigee/customer/application/message-processor.properties à l'aide de code with config (CwC) :

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

5. Redémarrez le processeur de messages :

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

Stratégie 4 : Options JVM (--add-opens / --add-exports — attention, à n'utiliser qu'en dernier recours)

Quand l'utiliser : utilisez cette stratégie en dernier recours pour les bibliothèques de fournisseurs tiers à code fermé dont le code source n'est pas disponible, pour lesquelles les fournisseurs n'ont pas publié de mises à jour Java 21 et dont le JAR dépend strictement de l'accès par réflexion aux packages Java internes.

Procédure :

1. Identifier le package inaccessible utilisé pour la réflexion : déterminez le module et le package Java internes auxquels votre bibliothèque tierce accède par réflexion. Remarque : Ces erreurs de réflexion se produisent uniquement sous Java 21 dans Edge for Private Cloud 4.54.00 et n'apparaissent pas dans les journaux de la version 4.53.x. Après la mise à niveau, vérifiez les journaux du processeur de messages (/opt/apigee/var/log/edge-message-processor/system.log) pour identifier le module et le package requis (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. Modifiez /opt/apigee/customer/application/message-processor.properties à l'aide de code with config (CwC) (créez le fichier s'il n'existe pas).
3. Ajoutez les options --add-opens ou --add-exports ciblées à 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. Assurez-vous que la propriété et les autorisations des fichiers sont correctes :

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

5. Redémarrez le processeur de messages à l'aide de apigee-service :

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

Modifications apportées au protocole TLS et à la suite d'algorithmes de chiffrement

Dans Edge for Private Cloud 4.54.00, les composants principaux de la plate-forme, y compris le processeur de messages, le serveur de gestion et le routeur, sont mis à jour pour s'exécuter sur Java 21 LTS. Cette mise à jour modernise la sécurité cryptographique en activant TLS 1.3 par défaut (JEP 332). Les processeurs de messages négocient désormais TLS 1.3 comme protocole préféré pour les connexions de backend sortantes, et reviennent à TLS 1.2 si le backend n'est pas compatible.

Exigences et correction concernant l'ancien backend

La référence cryptographique Java 21 met à jour la liste des protocoles et des suites de chiffrement désactivés par défaut dans jdk.tls.disabledAlgorithms (comme les anciens protocoles TLS et les suites d'échange de clés RSA statiques sans confidentialité persistante : TLS_RSA_*). Comme vous fournissez votre propre environnement d'exécution Java 21, la liste exacte des protocoles et des suites de chiffrement désactivés dépend de votre implémentation Java 21 spécifique.

Si vos proxys d'API existants se connectent à une ancienne infrastructure de backend qui nécessite des protocoles désactivés ou des chiffrements RSA statiques, examinez les actions suivantes :

• Moderniser la sécurité du backend (recommandé) : mettez à niveau les serveurs cibles et les équilibreurs de charge pour qu'ils soient compatibles avec TLS 1.2 ou TLS 1.3 avec des suites de chiffrement ECDHE modernes. Pour configurer des protocoles et des suites de chiffrement dans vos proxys d'API, consultez Configurer TLS d'Edge vers le backend et la documentation de référence sur la configuration TLS/SSL TargetEndpoint (ou Équilibrage de charge sur les serveurs backend si vous utilisez des TargetServers).
• Réactiver les anciens algorithmes à l'aide de CwC (mesure transitoire pendant la mise à niveau) : si les mises à niveau du backend ne peuvent pas être effectuées avant la mise à niveau de la plate-forme, vous pouvez réactiver temporairement les algorithmes requis à l'aide de code with config (CwC) :
  1. Vérifiez la valeur jdk.tls.disabledAlgorithms par défaut dans votre installation Java 21 (par exemple, dans $JAVA_HOME/conf/security/java.security).
  2. Remplacez conf_jvmsecurity_jdk.tls.disabledAlgorithms dans /opt/apigee/customer/application/message-processor.properties par la même liste d'algorithmes désactivés, en supprimant uniquement l'entrée TLS_RSA_* (conservez tous les autres algorithmes désactivés intacts afin que les protections restantes restent activées).
  3. Redémarrez le processeur de messages à l'aide de apigee-service. Supprimez ce remplacement une fois que le backend est compatible avec les suites de chiffrement ECDHE.
• Mettre à jour une liste d'autorisation de suites de chiffrement personnalisées : si vous avez déjà remplacé conf_http_HTTPTransport.ssl.cipher.suites.whitelist, vérifiez-le avant de procéder à la mise à niveau. Java 21 n'est plus compatible avec les suites RSA statiques (TLS_RSA_*). Par conséquent, une liste d'autorisation ne contenant que ces suites ne laisse aucun chiffrement utilisable au processeur de messages, et les appels de backend échouent avec l'erreur no cipher suites in common. Supprimez les entrées TLS_RSA_* et configurez des suites de chiffrement modernes compatibles avec votre implémentation Java 21. Si vous n'avez pas remplacé cette propriété, les valeurs par défaut de la version 4.54.00 incluent déjà les suites compatibles. Aucune modification n'est donc nécessaire.
• Mettez à jour les algorithmes de chiffrement internes du routeur vers le processeur de message : si vous avez déjà remplacé conf_message-processor-communication_local.http.ssl.ciphers par des suites RSA statiques, mettez-le à jour avec les suites de chiffrement modernes compatibles avec votre implémentation Java 21 avant la mise à niveau. Sinon, le routeur ne pourra pas effectuer de handshake TLS avec le processeur de message. Redémarrez ensuite le processeur de messages :

  apigee-service edge-message-processor restart

  Consultez Configurer TLS entre un routeur et un processeur de messages.

Pour en savoir plus sur la configuration de TLS entre les composants Edge, consultez Configurer TLS entre un routeur et un processeur de messages.

Outil de détection des modifications

Apigee fournit un outil de détection des modifications pour analyser votre cluster à la recherche de proxys d'API, de règles, de flux partagés et de JAR de ressources déployés qui pourraient être affectés par la mise à niveau vers Edge for Private Cloud 4.54.00.

L'outil identifie les potentiels blocages de mise à niveau, y compris les bibliothèques incompatibles avec Java 21, les API internes fortement encapsulées, les règles obsolètes et les limites RDN OpenLDAP. Il génère des rapports exploitables pour vous aider à sélectionner les stratégies de correction appropriées.

Pour connaître l'ensemble des conditions préalables, les instructions de téléchargement, la syntaxe de la ligne de commande et des exemples de rapports, consultez le guide dédié à l'outil de détection des modifications.