Modifiche in Edge for Private Cloud 4.54.00

Panoramica delle modifiche

Edge for Private Cloud 4.54.00 introduce diverse modifiche che migliorano la security posture della piattaforma e aggiorna i componenti della piattaforma per l'esecuzione con Java 21. Due delle sezioni riportate di seguito riguardano queste modifiche:

• Modifiche alla policy Java Callout
• Modifiche a TLS e suite di cifrari

Oltre a queste modifiche, consulta la guida dedicata allo strumento di rilevamento delle modifiche. Questa utilità è stata resa disponibile per identificare le modifiche ai proxy, ai flussi condivisi o ad altri artefatti nel cluster che potrebbero causare interruzioni a seguito di questo upgrade.

Tre funzionalità disponibili nella versione 4.53.01 non sono supportate in Edge for Private Cloud 4.54.00. Prima di pianificare l'upgrade, consulta Funzionalità non supportate nella versione 4.54.00.

Funzionalità non supportate nella versione 4.54.00

Edge for Private Cloud 4.54.00 non supporta le seguenti funzionalità, disponibili nella versione 4.53.01. Se il tuo deployment utilizza una di queste funzionalità, non eseguire l'upgrade alla versione 4.54.00. Rimani sulla versione 4.53.01 e contatta l'assistenza Apigee.

• Installazione su Google Distributed Cloud (GDC) con air gap. Edge for Private Cloud 4.54.00 non è certificato per gli ambienti GDC con air gap. Per la procedura della versione 4.53.01, consulta Installa Apigee su Google Distributed Cloud con air gap.
• RHEL 8.X o Rocky 8.X con FIPS abilitato. Edge for Private Cloud 4.54.00 non supporta l'installazione su un host RHEL 8.X o Rocky 8.X abilitato per FIPS. Questi sistemi operativi sono supportati quando la modalità FIPS non è abilitata. Gli argomenti di configurazione della versione 4.54.00 omettono anche le indicazioni specifiche per FIPS fornite dalla versione 4.53.01, tra cui la preparazione del keystore BCFKS, la proprietà di configurazione silenziosa FIPS_OS e la configurazione del keystore PKCS12. Per le indicazioni sulla versione 4.53.01, consulta Edge for Private Cloud su RHEL 8.X o Rocky 8.X abilitato per FIPS.
• Integrazione del modulo di sicurezza hardware (HSM) southbound. Edge for Private Cloud 4.54.00 non supporta le connessioni TLS verso sud dai processori di messaggi ai servizi di destinazione di backend che utilizzano un HSM di rete Entrust nShield. Per la procedura della versione 4.53.01, consulta la Guida all'integrazione del modulo di sicurezza hardware southbound per Apigee Edge for Private Cloud.

Modifiche alla policy callout Java

In Edge for Private Cloud 4.54.00, i componenti principali della piattaforma, tra cui il processore di messaggi, il server di gestione e il router, vengono aggiornati per l'esecuzione su Java 21 LTS. Java 21 modernizza la piattaforma Java, il che include la rimozione dei moduli Java EE e CORBA legacy (JEP 320), la rimozione delle classi di utilità interne legacy e l'applicazione di un'incapsulamento modulare forte (JEP 403).

A causa di queste modifiche, i proxy API con policy JavaCallout personalizzate o JAR di risorse personalizzati (archiviati a livello di proxy, ambiente o organizzazione) potrebbero subire interruzioni durante l'upgrade alla versione 4.54.00.

Categorie di modifiche che potrebbero influire sui callout Java

1. Rimozione definitiva dei moduli Java EE e CORBA (JEP 320): i moduli precedentemente integrati nel runtime Java 8 (tra cui JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.* e CORBA org.omg.*) sono stati rimossi da Java SE. I callout che fanno riferimento a questi pacchetti senza raggruppare sostituzioni autonome non vanno a buon fine in fase di runtime con NoClassDefFoundError.
2. Rimozione delle classi di utilità interne:sono stati rimossi gli helper interni legacy come sun.misc.BASE64Encoder e sun.misc.BASE64Decoder. I callout che chiamano queste classi non vanno a buon fine con NoClassDefFoundError.
3. Forte incapsulamento degli elementi interni di Java (JEP 403): non è possibile accedere ai pacchetti interni in java.base (come sun.security.*, sun.reflect.* e com.sun.*) in modo riflessivo dai callout personalizzati. Le chiamate riflessive non vanno a buon fine in fase di runtime con InaccessibleObjectException.
4. Modifiche e rimozioni delle firme dei metodi nelle classi Java sopravvissute: in alcuni moduli Java, la classe rimane presente in Java 21, ma costruttori o firme dei metodi specifici sono stati rimossi, ritirati o modificati (ad esempio metodi di analisi DOM specifici in org.w3c.dom.Document e classi di analisi XML correlate).

   Rilevamento dello strumento: lo strumento di rilevamento delle modifiche segnala i riferimenti a queste classi nella categoria METHOD_SIGNATURE_MODIFICATION con MEDIUM di certezza dell'impatto, invitando gli sviluppatori a ispezionare il codice sorgente dei callout per individuare le chiamate ai metodi modificate.

Strategie di correzione

Prima di eseguire l'upgrade, assicurati che le policy di callout Java e le risorse JAR personalizzate siano compatibili con il runtime Java 21. L'utilizzo dello strumento di rilevamento delle modifiche ti aiuterà a identificare i proxy API, i flussi condivisi e le risorse JAR dell'ambiente o dell'organizzazione interessati nel tuo cluster.

Le strategie di correzione descritte in questa sezione sono guide generali e non si escludono a vicenda. A seconda dei requisiti operativi, puoi combinare le strategie, ad esempio modernizzando il codice sorgente del callout utilizzando la Strategia 2 e implementando le revisioni del proxy aggiornate utilizzando la Strategia 3B per ottenere tempi di inattività pari a zero durante gli upgrade del processore di messaggi.

Le strategie 3A, 3B e 3C sono tre modi per eseguire lo stesso approccio operativo: eseguire l'upgrade del nodo e rifare il deployment del proxy in momenti diversi, senza modificare il bundle del proxy. Scegli una o una combinazione di queste opzioni in base ai requisiti di disponibilità delle API.

Consulta la seguente guida alle decisioni per selezionare l'approccio più appropriato per il tuo deployment:

Guida alle decisioni per le mitigazioni dei callout Java:

Strategia 1: proxy con doppia compatibilità tramite JAR in bundle (test prima dell'upgrade per evitare tempi di inattività)

Quando utilizzarla:utilizza questa strategia quando:

• È disponibile una libreria sostitutiva autonoma con doppia compatibilità: esiste un JAR sostitutivo che implementa la funzionalità richiesta e può essere raggruppato direttamente nel proxy API senza richiedere modifiche al codice sorgente.
• Vuoi che i proxy API e i callout Java esistenti funzionino senza problemi sia sulla versione attuale (ad esempio Edge for Private Cloud 4.53.01) sia sulla versione aggiornata (Edge for Private Cloud 4.54.00).
• Devi testare e verificare tutte le modifiche negli ambienti di gestione temporanea e di produzione prima di eseguire l'upgrade del cluster Edge for Private Cloud, per evitare problemi imprevisti e tempi di inattività nel traffico in tempo reale.
• Vuoi evitare di riscrivere o rifattorizzare la logica di business del callout Java.

Come funziona: in Java 8, alcune librerie (come JAXB javax.xml.bind.* o Activation javax.activation.*) erano integrate direttamente nel runtime di Java 8. Per questo motivo, gli sviluppatori non dovevano includere file JAR aggiuntivi nei bundle proxy. In Java 21, queste librerie sono state rimosse dal runtime Java.

Per rendere il proxy "compatibile con entrambi" Edge for Private Cloud 4.53.x e 4.54.00:

1. Identifica la libreria mancante richiesta dal callout (ad esempio JAXB o Activation).
2. Acquisisci il JAR sostitutivo open source autonomo (ad esempio, jakarta.xml.bind-api-2.3.3.jar e jaxb-runtime-2.3.8.jar).
3. Inserisci il JAR sostitutivo direttamente nel bundle proxy in apiproxy/resources/java/, caricalo nella revisione del proxy utilizzando l'API Resource Files a livello di proxy o caricalo come file di risorse a livello di ambiente o livello di organizzazione. Per ulteriori informazioni sulla gestione dei file di risorse, consulta la documentazione sui file di risorse di Apigee.
4. Esegui il deployment e i test prima dell'upgrade: i processori di messaggi sia in Edge for Private Cloud 4.53.x che in 4.54.00 caricano le classi da questi JAR in bundle. Ora puoi eseguire il deployment di questo bundle di proxy aggiornato e testarlo con il traffico sintetico nel tuo cluster Edge for Private Cloud 4.53.x attuale.
5. Abilita il caricamento di pacchetti esterni consentiti sui processori di messaggi (obbligatorio per la versione 4.54.00): per impostazione predefinita in Edge for Private Cloud 4.54.00, il caricamento dei pacchetti Java rimossi (come javax.xml.bind.* e javax.activation.*) da JAR di risorse esterne o in bundle è disabilitato (conf_system_java.21.enable.external.allowed.packages=false), pertanto il raggruppamento dei JAR da solo non funzionerà per impostazione predefinita. Devi attivare questa proprietà in /opt/apigee/customer/application/message-processor.properties utilizzando il codice con configurazione (CwC) (puoi configurare questa proprietà prima di eseguire l'upgrade del nodo del processore di messaggi o impostarla dopo l'upgrade e riavviare il processore di messaggi):

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

6. Nessun problema di traffico in tempo reale dopo l'upgrade: quando successivamente viene eseguito l'upgrade del cluster a Edge for Private Cloud 4.54.00 con conf_system_java.21.enable.external.allowed.packages=true abilitato, il processore di messaggi ha già il JAR richiesto disponibile e carica le classi dal file di risorse in bundle senza errori (NoClassDefFoundError), garantendo un upgrade fluido e senza tempi di inattività.

Esempio di codice: callout di convalida e analisi XML dell'ordine

Prendi in considerazione un tipico callout Java di Apigee che estrae e convalida gli ordini XML in entrata utilizzando JAXB (JAXBContext e Unmarshaller).

• Prima della correzione (non funziona in Edge for Private Cloud 4.54.00): in Edge for Private Cloud 4.53.x, il bundle del proxy contiene solo il JAR del callout, basandosi sulle librerie di runtime Java 8 integrate per JAXB:

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

  L'implementazione del callout 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) { }
      }
  }

  L'errore: in Edge for Private Cloud 4.53.x, l'esecuzione avviene senza problemi. Una volta eseguito l'upgrade del nodo a Edge for Private Cloud 4.54.00, questo proxy non riesce immediatamente durante l'elaborazione della richiesta:

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

• Dopo la correzione (compatibile con Edge for Private Cloud 4.53.x e 4.54.00): non è necessario riscrivere o ricompilare il codice callout Java. Puoi rendere il tuo proxy direttamente compatibile con entrambi i protocolli fornendo i file JAR autonomi:
  1. Aggrega o carica direttamente i JAR autonomi: ottieni le librerie JAXB autonome (jakarta.xml.bind-api-2.3.3.jar e jaxb-runtime-2.3.8.jar) e inseriscile nel bundle proxy in apiproxy/resources/java/:

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

     In alternativa, carica jakarta.xml.bind-api-2.3.3.jar e jaxb-runtime-2.3.8.jar come file di risorse utilizzando l'API Resource Files a livello di proxy o a livello di ambiente o livello di organizzazione in modo che tutti i proxy nello stesso ambito possano condividerli senza raggrupparli in ogni singolo bundle di proxy.

     Se crei il bundle del proxy dal codice sorgente utilizzando Maven, dichiara queste dipendenze nel file pom.xml in modo che vengano pacchettizzate automaticamente durante la build.

  2. Esegui il deployment e il test sul cluster 4.53.x attuale: esegui il deployment del bundle proxy aggiornato nell'ambiente Edge for Private Cloud 4.53.x esistente e invia chiamate di test. Poiché i processori di messaggi di Edge for Private Cloud 4.53.x caricano le classi da questi JAR in bundle, puoi verificare che il callout continui a funzionare in modo identico.
  3. Abilita il caricamento dei pacchetti esterni consentiti tramite CwC: poiché il caricamento dei pacchetti esterni consentiti è disabilitato per impostazione predefinita in Edge for Private Cloud 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false), abilitalo su ogni nodo processore di messaggi in /opt/apigee/customer/application/message-processor.properties utilizzando il codice con configurazione (CwC):

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

  4. Nessun problema di traffico in tempo reale dopo l'upgrade: una volta convalidato nell'ambiente 4.53.x e configurato con la proprietà CwC, il proxy è completamente pronto. Quando esegui l'upgrade del cluster a Edge for Private Cloud 4.54.00, il processore di messaggi carica le classi JAXB in bundle, garantendo zero errori e zero interruzioni del traffico in tempo reale.

Strategia 2: implementazione alternativa (modernizzazione del codice e delle dipendenze)

Quando utilizzarlo: consigliato per codebase attive in cui il codice sorgente del proxy viene gestito facilmente. Questo è l'approccio a lungo termine più pulito per la conformità a Java 21. Nota sull'implementazione: poiché il deployment delle revisioni dei proxy modernizzati richiede il coordinamento dei processori di messaggi, abbina questa strategia alla Strategia 3A (durante un periodo di manutenzione pianificato) o alla Strategia 3B (per ottenere tempi di inattività pari a zero con processori di messaggi paralleli).

Come funziona: sostituisci le classi interne Java rimosse con API Java SE standard ufficiali o equivalenti autonomi open source e pacchettizza le dipendenze di terze parti richieste direttamente nei file di risorse del bundle proxy o nel POM.

Esempi di codice:

Esempio 1: modernizzazione di metodi e codice (sostituzione delle utilità interne rimosse)

In Java 8, i callout utilizzavano spesso classi di utilità interne come sun.misc.BASE64Encoder. In Java moderno, queste classi sono state rimosse, ma l'API java.util.Base64 standard fornisce sostituzioni dirette senza richiedere JAR di dipendenza esterni:

• Prima (implementazione Java 8 legacy):

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

• Dopo (implementazione conforme a 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;
      }
  }

Esempio 2: rifattorizzazione a livello di importazione con libreria in bundle (JAXB Namespace Prefix Mapper)

In Java 8, i proxy API che personalizzano i prefissi degli spazi dei nomi XML estendevano comunemente il mapper JAXB interno di Sun com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. In Java 21, i pacchetti Sun interni vengono rimossi e non sono accessibili.

La libreria open source autonoma (org.glassfish.jaxb:jaxb-runtime) fornisce la stessa classe in com.sun.xml.bind.marshaller.NamespacePrefixMapper. Tutte le firme, i parametri e i tipi restituiti dei metodi sono identici: la modifica del codice avviene esclusivamente nell'istruzione di importazione:

• Prima (implementazione Java 8 legacy):

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

• Dopo (implementazione conforme a 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;
      }
  }

• Configurazione delle dipendenze in bundle (pom.xml): per fornire questa classe in fase di runtime, raggruppa le librerie JAXB autonome all'interno di apiproxy/resources/java/ o dichiarale in 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>

Strategia 3A: tempi di inattività per manutenzione pianificata (rifare il deployment in loco)

Quando utilizzarlo: consigliato per ambienti con periodi di manutenzione operativa pianificati in cui è accettabile una breve interruzione del servizio.

Procedura:

1. Coordinare un periodo di manutenzione pianificato con i consumer di API.
2. Esegui l'upgrade dei componenti di Edge for Private Cloud alla versione 4.54.00 seguendo la guida ai percorsi di upgrade.
3. Esegui il deployment della revisione precompilata e compatibile con la versione 4.54.00 del proxy API utilizzando la UI di New Edge o l'API di gestione di Apigee (Deployment).
4. Verifica l'esecuzione del callout inviando richieste di test sintetici ai processori di messaggi e ispezionando i log utilizzando lo strumento Trace.
5. Chiudi il periodo di manutenzione e riapri il traffico pubblico.

Strategia 3B: crea un nuovo ambiente (migrazione senza tempi di inattività)

Quando utilizzarlo: consigliato per ambienti di produzione mission-critical che richiedono tempi di inattività pari a zero. Utilizza questa opzione quando il callout Java non può essere aggiornato per funzionare contemporaneamente su Java 8 e Java 21.

Come funziona: questa strategia prevede l'approvvigionamento di uno o più nuovi ambienti in modo da poter collegare i nodi del processore di messaggi di versioni diverse. Successivamente, esegui il deployment dei proxy compatibili con Java 8 nell'ambiente collegato ai processori di messaggi 4.53.X e dei proxy compatibili con Java 21 nell'ambiente collegato ai processori di messaggi 4.54.00. Quindi, utilizza un bilanciatore del carico o altre tecniche di routing per instradare il traffico solo al proxy compatibile con Java 21.

Per questa strategia, comprendere il modo in cui organizzazioni, ambienti e processori di messaggi interagiscono è fondamentale per un cutover senza tempi di inattività (per ulteriori informazioni, consulta Struttura dell'organizzazione Apigee Edge):

• Un'organizzazione Apigee è un confine amministrativo di primo livello contenente più ambienti (ad esempio prod, test).
• Il deployment di una revisione del proxy API viene eseguito in un ambiente specifico. Solo i processori di messaggi associati esplicitamente a quell'ambiente caricano ed eseguono la revisione del 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        |
          +------------------------------------------------------+

Procedura:

1. Crea un ambiente temporaneo: crea un nuovo ambiente (ad esempio prod-migration) all'interno della tua organizzazione (seguendo la procedura descritta in Configurazione di host e ambienti virtuali) con un host virtuale e una porta dedicati.
2. Esegui il provisioning dei nodi processore di messaggi 4.54.00: installa Edge for Private Cloud 4.54.00 su istanze VM nuove o temporanee e associa questi nodi a prod-migration (consulta Aggiunta di un processore di messaggi).
3. Identifica i proxy interessati e crea revisioni aggiornate: identifica i proxy API che utilizzano i callout Java (utilizzando lo strumento di rilevamento delle modifiche) e crea una nuova revisione di ogni proxy interessato con i callout Java compatibili con Edge for Private Cloud 4.54.00 (applicando la Strategia 1 o la Strategia 2).
4. Esegui il deployment delle revisioni del proxy modernizzate nell'ambiente temporaneo:esegui il deployment delle revisioni del proxy aggiornate e compatibili esclusivamente in prod-migration.
5. Verifica e sposta il traffico: esegui test di verifica sintetici sull'host virtuale nuovo. Una volta eseguita la verifica, configura il bilanciatore del carico esterno (F5, NGINX) per reindirizzare il traffico client da prod a prod-migration.
6. Esegui l'upgrade dei nodi originali e torna indietro: annulla il deployment dei proxy legacy da prod. Esegui l'upgrade dei nodi processore di messaggi originali alla versione 4.54.00 seguendo la guida ai percorsi di upgrade. Esegui il deployment delle revisioni dei proxy modernizzati in prod, reindirizza il traffico del bilanciatore del carico a prod e verifica il funzionamento.
7. Dismettere l'ambiente temporaneo: annulla il deployment dei proxy da prod-migration, rimuovi i nodi del processore di messaggi temporanei ed elimina l'ambiente temporaneo.

Strategia 3C: posizionamento di librerie esterne a livello di nodo (librerie di riserva condivise)

Quando utilizzarla: consigliata se hai più proxy API che si basano su classi Java rimosse in Java 21 e la ricompilazione o il riconfezionamento di ogni singolo bundle di proxy prima dell'upgrade non è fattibile dal punto di vista operativo.

Come funziona: in Edge for Private Cloud 4.54.00, i processori di messaggi forniscono un meccanismo per caricare le classi Java mancanti da una directory dei nodi dedicata: $APIGEE_ROOT/data/edge-message-processor/external-lib.

Quando questo meccanismo è abilitato, il processore di messaggi controlla questa directory per verificare la presenza di classi mancanti prima di tornare alla risoluzione predefinita. Puoi fornire le classi mancanti recuperandole da JAR di librerie di terze parti o raggruppando le classi richieste in un JAR e inserendolo in external-lib.

Procedura:

1. Crea la directory della libreria esterna su ogni nodo del processore di messaggi:

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

2. Inserisci i file JAR richiesti nella directory: copia i file JAR contenenti le classi richieste in /opt/apigee/data/edge-message-processor/external-lib.
3. Imposta le autorizzazioni dei file appropriate:assicurati che l'utente del servizio apigee disponga delle autorizzazioni in lettura:

   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. Abilita il caricamento di pacchetti esterni nella configurazione del processore di messaggi: per impostazione predefinita in Edge for Private Cloud 4.54.00, il caricamento di pacchetti esterni consentiti è disabilitato (conf_system_java.21.enable.external.allowed.packages=false). Per consentire al processore di messaggi di risolvere e caricare le classi da /opt/apigee/data/edge-message-processor/external-lib, devi abilitare questa proprietà in /opt/apigee/customer/application/message-processor.properties utilizzando code with config (CwC):

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

5. Riavvia il processore di messaggi:

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

Strategia 4: flag JVM (--add-opens / --add-exports - attenzione e ultima risorsa)

Quando utilizzarla: utilizza questa strategia come ultima risorsa per le librerie di fornitori di terze parti closed source in cui il codice sorgente non è disponibile, i fornitori non hanno rilasciato aggiornamenti di Java 21 e il JAR dipende rigorosamente dall'accesso riflessivo ai pacchetti Java interni.

Procedura:

1. Identifica il pacchetto inaccessibile utilizzato per la reflection:determina il modulo e il pacchetto Java interni a cui la libreria di terze parti accede in modo riflessivo. Nota: questi errori di riflessione si verificano esclusivamente in Java 21 in Edge for Private Cloud 4.54.00 e non vengono visualizzati nei log della versione 4.53.x. Controlla i log del processore di messaggi (/opt/apigee/var/log/edge-message-processor/system.log) dopo l'upgrade per InaccessibleObjectException identificando il modulo e il pacchetto richiesti:

   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. Modifica /opt/apigee/customer/application/message-processor.properties utilizzando code with config (CwC) (crea il file se non esiste).
3. Aggiungi i flag --add-opens o --add-exports di destinazione a 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. Assicurati che la proprietà e le autorizzazioni dei file siano corrette:

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

5. Riavvia il processore di messaggi utilizzando apigee-service:

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

Modifiche a TLS e suite di cifrari

In Edge for Private Cloud 4.54.00, i componenti principali della piattaforma, tra cui il processore di messaggi, il server di gestione e il router, vengono aggiornati per l'esecuzione su Java 21 LTS. Questo aggiornamento modernizza la sicurezza crittografica abilitando TLS 1.3 per impostazione predefinita (JEP 332). I processori di messaggi ora negoziano TLS 1.3 come protocollo preferito per le connessioni di backend in uscita, tornando a TLS 1.2 se il backend non lo supporta.

Requisiti e correzione dei backend legacy

La baseline crittografica di Java 21 aggiorna l'elenco di protocolli e suite di cifrari disattivati per impostazione predefinita in jdk.tls.disabledAlgorithms (come i protocolli TLS legacy e le suite di scambio di chiavi RSA statiche non forward-secret: TLS_RSA_*). Poiché fornisci il tuo runtime Java 21, l'elenco esatto di protocolli e suite di cifrari disattivati dipende dalla tua specifica implementazione di Java 21.

Se i proxy API esistenti si connettono a un'infrastruttura di backend legacy che richiede protocolli disabilitati o crittografie RSA statiche, esamina le seguenti azioni:

• Modernizza la sicurezza del backend (consigliato): esegui l'upgrade dei server di destinazione e dei bilanciatori del carico per supportare TLS 1.2 o TLS 1.3 con suite di cifrari ECDHE moderne. Per configurare protocolli e suite di crittografia nei proxy API, consulta Configurazione di TLS da Edge al backend e il riferimento per la configurazione di TargetEndpoint TLS/SSL (o Bilanciamento del carico tra i server di backend se utilizzi TargetServers).
• Riattiva gli algoritmi legacy utilizzando CwC (misura transitoria durante l'upgrade): se gli upgrade del backend non possono essere completati prima dell'upgrade della piattaforma, puoi riattivare temporaneamente gli algoritmi richiesti utilizzando code with config (CwC):
  1. Controlla il valore predefinito di jdk.tls.disabledAlgorithms nell'installazione di Java 21 (ad esempio in $JAVA_HOME/conf/security/java.security).
  2. Esegui l'override di conf_jvmsecurity_jdk.tls.disabledAlgorithms in /opt/apigee/customer/application/message-processor.properties con lo stesso elenco di algoritmi disattivati, rimuovendo solo la voce TLS_RSA_* (mantieni intatti tutti gli altri algoritmi disattivati in modo che le protezioni rimanenti rimangano attive).
  3. Riavvia il processore di messaggi utilizzando apigee-service. Rimuovi questo override una volta che il backend supporta le suite di cifrari ECDHE.
• Aggiorna una lista consentita di suite di crittografia personalizzata:se in precedenza hai eseguito l'override di conf_http_HTTPTransport.ssl.cipher.suites.whitelist, esaminalo prima di eseguire l'upgrade. Java 21 non supporta più le suite RSA statiche (TLS_RSA_*), pertanto una lista consentita che contiene solo queste suite lascia il processore di messaggi senza un algoritmo di crittografia utilizzabile e le chiamate al backend non vanno a buon fine con no cipher suites in common. Rimuovi le voci TLS_RSA_* e configura suite di crittografia moderne supportate dalla tua implementazione di Java 21. Se non hai eseguito l'override di questa proprietà, i valori predefiniti della versione 4.54.00 contengono già le suite supportate e non è necessaria alcuna modifica.
• Aggiorna i cifrari interni da Router a processore di messaggi: se in precedenza hai eseguito l'override di conf_message-processor-communication_local.http.ssl.ciphers con suite RSA statiche, aggiornalo con suite di cifrari moderne supportate dalla tua implementazione di Java 21 prima di eseguire l'upgrade, altrimenti il Router non potrà completare un TLS handshake con il processore di messaggi. Quindi riavvia il processore di messaggi:

  apigee-service edge-message-processor restart

  Consulta Configurazione di TLS tra un router e un processore di messaggi.

Per informazioni dettagliate sulla configurazione di TLS tra i componenti Edge, consulta Configurazione di TLS tra un router e un processore di messaggi.

Strumento di rilevamento delle modifiche

Apigee fornisce uno strumento di rilevamento delle modifiche per analizzare il cluster alla ricerca di proxy API, policy, flussi condivisi e JAR di risorse di cui è stato eseguito il deployment che potrebbero essere interessati dall'upgrade a Edge for Private Cloud 4.54.00.

Lo strumento identifica i potenziali ostacoli all'upgrade, tra cui librerie incompatibili con Java 21, API interne fortemente incapsulate, deprecazioni delle policy legacy e limiti RDN di OpenLDAP, e genera report utili per aiutarti a selezionare le strategie di correzione appropriate.

Per i prerequisiti completi, le istruzioni per il download, la sintassi della riga di comando e i report di esempio, consulta la guida allo strumento di rilevamento delle modifiche dedicata.