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.

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 e restituiscono 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 di reflection 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 a doppia compatibilità tramite file JAR inclusi nel 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 saperne di più sulla gestione dei file di risorse, consulta la documentazione sui file di risorse 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 di pacchetti Java rimossi (come javax.xml.bind.* e javax.activation.*) da JAR di risorse esterni o in bundle è disabilitato (conf_system_java.21.enable.external.allowed.packages=false), quindi 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 per l'analisi e la convalida XML dell'ordine

Prendi in considerazione un tipico callout Java 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 funziona immediatamente durante l'elaborazione delle richieste:

  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 proxy direttamente compatibile con entrambe le versioni 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 di organizzazione, in modo che tutti i proxy con lo 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 Edge for Private Cloud 4.53.x caricano le classi da questi file JAR in bundle, puoi verificare che il callout continui a funzionare in modo identico.
  3. Abilita il caricamento di pacchetti consentiti esterni tramite CwC:poiché il caricamento di pacchetti consentiti esterni è disattivato 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 code with config (CwC):

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

  4. Nessun problema di traffico live 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 sul rilascio: poiché il deployment delle revisioni del proxy modernizzate richiede il coordinamento del processore di messaggi, abbina questa strategia alla strategia 3A (durante un periodo di manutenzione pianificato) o alla strategia 3B (per ottenere tempi di inattività nulli 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: tempo di inattività per manutenzione pianificata (ridistribuzione 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 la callout Java non può essere aggiornata per funzionare contemporaneamente con Java 8 e Java 21.

Come funziona:questa strategia prevede l'acquisizione 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 cablato con i processori di messaggi 4.53.X e dei proxy compatibili con Java 21 nell'ambiente cablato con i 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 limite amministrativo di primo livello che contiene 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 esplicitamente associati 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 temporaneo ed elimina l'ambiente temporaneo.

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

Quando utilizzare: consigliato quando hai più proxy API che si basano su classi Java rimosse in Java 21 e la ricompilazione o il reimpacchettamento di ogni singolo bundle di proxy prima dell'upgrade è operativamente irrealizzabile.

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 le classi mancanti prima di ricorrere 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 di 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 targeting 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 del 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 tuoi proxy API esistenti si connettono a un'infrastruttura di backend legacy che richiede protocolli disabilitati o cifrari RSA statici, 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 crittografia 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 includono già le suite supportate e non è necessaria alcuna modifica.
• Aggiorna le cifrature del router interno al processore di messaggi:se in precedenza hai sostituito conf_message-processor-communication_local.http.ssl.ciphers con suite RSA statiche, aggiornale con suite di cifre moderne supportate dall'implementazione di Java 21 prima dell'upgrade, altrimenti il router non può completare l'handshake TLS 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, criteri, flussi condivisi e JAR di risorse di cui è stato eseguito il deployment e che potrebbero essere interessati dall'upgrade a Edge for Private Cloud 4.54.00.

Lo strumento identifica i potenziali blocchi dell'upgrade, tra cui librerie incompatibili con Java 21, API interne fortemente incapsulate, ritiri di policy legacy e limiti RDN OpenLDAP, e produce report utilizzabili 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.