Mudanças no Edge para nuvem privada 4.54.00

Visão geral das mudanças

O Edge para nuvem privada 4.54.00 apresenta várias mudanças que melhoram a postura de segurança da plataforma e atualiza os componentes dela para serem executados com o Java 21. Duas das seções abaixo abordam essas mudanças:

• Mudanças na política de chamada de Java
• Mudanças no TLS e no pacote de criptografia

Além dessas mudanças, consulte o guia dedicado à ferramenta de detecção de mudanças. Esse utilitário foi disponibilizado para identificar mudanças em proxies, fluxos compartilhados ou outros artefatos no cluster que possam causar interrupções como resultado desse upgrade.

Três recursos disponíveis na versão 4.53.01 não são compatíveis com o Edge para nuvem privada 4.54.00. Antes de planejar o upgrade, consulte Recursos não compatíveis com a versão 4.54.00.

Recursos não compatíveis com a versão 4.54.00

O Edge para nuvem privada 4.54.00 não é compatível com os seguintes recursos, que estão disponíveis na versão 4.53.01. Se a implantação usar algum deles, não faça upgrade para a versão 4.54.00. Permaneça na versão 4.53.01 e entre em contato com o suporte da Apigee.

• Instalação no Google Distributed Cloud (GDC) com isolamento físico. O Edge para nuvem privada 4.54.00 não é certificado para ambientes do GDC com isolamento físico. Para o procedimento da versão 4.53.01, consulte Instalar a Apigee no Google Distributed Cloud com isolamento físico.
• RHEL 8.X ou Rocky 8.X com FIPS ativado. O Edge para nuvem privada 4.54.00 não é compatível com a instalação em um host RHEL 8.X ou Rocky 8.X com FIPS ativado. Estes sistemas operacionais são compatíveis quando o modo FIPS não está ativado. Os tópicos de configuração da versão 4.54.00 também omitem as orientações específicas do FIPS fornecidas pela versão 4.53.01, incluindo a preparação do keystore BCFKS, a propriedade de configuração silenciosa FIPS_OS e a configuração do keystore PKCS12. Para orientações sobre a versão 4.53.01, consulte Edge para nuvem privada no RHEL 8.X ou Rocky 8.X com FIPS ativado.
• Integração do módulo de segurança de hardware (HSM) de saída. O Edge para nuvem privada 4.54.00 não é compatível com conexões TLS de saída dos processadores de mensagens para serviços de destino de back-end que usam um HSM de rede Entrust nShield. Para o procedimento da versão 4.53.01, consulte o Guia de integração do módulo de segurança de hardware de saída para a Apigee Edge para nuvem privada.

Mudanças na política de chamada de Java

No Edge para nuvem privada 4.54.00, os principais componentes da plataforma, incluindo o processador de mensagens, o servidor de gerenciamento e o roteador, foram atualizados para serem executados no Java 21 LTS. O Java 21 moderniza a plataforma Java, o que inclui a remoção de módulos legados do Java EE e do CORBA (JEP 320), a remoção de classes de utilitários internos legados e a aplicação de um encapsulamento modular forte (JEP 403).

Devido a essas mudanças, os proxies de API com políticas JavaCallout personalizadas ou JARs de recursos personalizados (armazenados no nível do proxy, do ambiente ou da organização) podem sofrer interrupções ao fazer upgrade para a versão 4.54.00.

Categorias de mudanças que podem afetar as chamadas de Java

1. Módulos Java EE e CORBA removidos permanentemente (JEP 320): os módulos criados anteriormente no ambiente de execução do Java 8 (incluindo JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.* e CORBA org.omg.*) foram removidos do Java SE. As chamadas que fazem referência a esses pacotes sem agrupar substituições independentes falham no momento da execução com NoClassDefFoundError.
2. Classes de utilitários internos removidas:os auxiliares internos legados, como sun.misc.BASE64Encoder e sun.misc.BASE64Decoder, foram removidos. As chamadas que usam essas classes falham com NoClassDefFoundError.
3. Encapsulamento forte de componentes internos do Java (JEP 403): os pacotes internos em java.base (como sun.security.*, sun.reflect.* e com.sun.*) não podem ser acessados de forma reflexiva em frases de destaque personalizadas. As chamadas reflexivas falham no momento da execução com InaccessibleObjectException.
4. Alterações e remoções de assinatura de método em classes Java sobreviventes:em determinados módulos Java, a classe permanece presente no Java 21, mas construtores ou assinaturas de método específicos foram removidos, descontinuados ou alterados (como métodos específicos de análise de DOM em org.w3c.dom.Document e classes de análise de XML relacionadas).

   Detecção de ferramentas:a ferramenta de detecção de mudanças sinaliza referências a essas classes na categoria METHOD_SIGNATURE_MODIFICATION com MEDIUM Impact Certainty, solicitando que os desenvolvedores inspecionem o código-fonte das chamadas para invocações de métodos modificados.

Estratégias de correção

Antes de fazer upgrade, verifique se as políticas de chamada de Java e os recursos JAR personalizados são compatíveis com o ambiente de execução do Java 21. Usar a ferramenta de detecção de mudanças ajuda a identificar proxies de API, fluxos compartilhados e recursos JAR de ambiente ou organização afetados no cluster.

As estratégias de correção descritas nesta seção são guias gerais e não são mutuamente exclusivas. Dependendo dos seus requisitos operacionais, é possível combinar estratégias. Por exemplo, modernizar o código-fonte de callout usando a Estratégia 2 e implantar as revisões de proxy atualizadas usando a Estratégia 3B para que não haja inatividade durante os upgrades do processador de mensagens.

As estratégias 3A, 3B e 3C são três maneiras de realizar a mesma abordagem operacional: fazer upgrade do nó e reimplantar o proxy em momentos diferentes, sem mudar o pacote de proxy. Escolha uma ou uma combinação delas com base nos requisitos de disponibilidade da API.

Consulte o guia de decisão a seguir para selecionar a abordagem mais adequada para sua implantação:

Guia de decisão para mitigações de chamadas de Java:

Estratégia 1: proxy de compatibilidade dupla com JARs em pacote (teste antes do upgrade para não ter tempo de inatividade)

Quando usar:use essa estratégia quando:

• Uma biblioteca de substituição independente com compatibilidade dupla está disponível:existe um JAR de substituição que implementa a funcionalidade necessária e pode ser agrupado diretamente no proxy de API sem exigir modificações no código-fonte.
• Você quer que os proxies de API e as chamadas de Java funcionem perfeitamente na versão atual (por exemplo, Edge para nuvem privada 4.53.01) e na versão atualizada (Edge para nuvem privada 4.54.00).
• Você quer testar e verificar todas as mudanças nos ambientes de preparo e produção antes de fazer upgrade do cluster do Edge para nuvem privada, garantindo que não haja problemas inesperados nem tempo de inatividade no tráfego em tempo real.
• Você quer evitar reescrever ou refatorar a lógica de negócios da chamada de Java.

Como funciona:no Java 8, algumas bibliotecas (como JAXB javax.xml.bind.* ou Activation javax.activation.*) foram criadas diretamente no ambiente de execução do Java 8. Por isso, os desenvolvedores não precisavam incluir arquivos JAR extras nos pacotes de proxy. No Java 21, essas bibliotecas foram removidas do ambiente de execução do Java.

Para tornar seu proxy "compatível com os dois" no Edge para nuvem privada 4.53.x e 4.54.00:

1. Identifique a biblioteca ausente exigida pela chamada (por exemplo, JAXB ou Activation).
2. Adquira o JAR de substituição de código aberto independente (por exemplo, jakarta.xml.bind-api-2.3.3.jar e jaxb-runtime-2.3.8.jar).
3. Coloque o JAR de substituição diretamente no pacote de proxy em apiproxy/resources/java/, faça upload dele para a revisão de proxy usando a API Resource Files no nível do proxy ou faça upload dele como um arquivo de recurso no nível do ambiente ou da organização. Para mais informações sobre como gerenciar arquivos de recursos, consulte a documentação sobre arquivos de recursos da Apigee.
4. Implante e teste antes do upgrade:os processadores de mensagens no Edge para nuvem privada 4.53.x e 4.54.00 carregam classes desses JARs agrupados. É possível implantar esse pacote de proxy atualizado e testá-lo com tráfego sintético no cluster atual do Edge para nuvem privada 4.53.x.
5. Ativar o carregamento de pacotes externos permitidos em processadores de mensagens (obrigatório para a versão 4.54.00): por padrão, no Edge para nuvem privada 4.54.00, o carregamento de pacotes Java removidos (como javax.xml.bind.* e javax.activation.*) de JARs de recursos externos ou agrupados está desativado (conf_system_java.21.enable.external.allowed.packages=false). Portanto, o agrupamento de JARs por conta própria não vai funcionar por padrão. Ative essa propriedade em /opt/apigee/customer/application/message-processor.properties usando o código com configuração (CwC). É possível configurar essa propriedade antes de fazer upgrade do nó do processador de mensagens ou defini-la após o upgrade e reiniciar o processador de mensagens:

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

6. Zero problemas de tráfego em tempo real após o upgrade:quando o cluster é atualizado para o Edge para nuvem privada 4.54.00 com o conf_system_java.21.enable.external.allowed.packages=true ativado, o processador de mensagens já tem o JAR necessário disponível e carrega as classes do arquivo de recurso incluído sem falhas (NoClassDefFoundError), garantindo um upgrade tranquilo e sem inatividade.

Exemplo de código: validação de XML de pedido e callout de análise

Considere uma chamada de Java típica da Apigee que extrai e valida pedidos XML recebidos usando JAXB (JAXBContext e Unmarshaller).

• Antes da correção (falha no Edge para nuvem privada 4.54.00): no Edge para nuvem privada 4.53.x, o pacote de proxy contém apenas o JAR de chamada, que depende das bibliotecas de ambiente de execução integradas do Java 8 para o JAXB:

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

  A implementação da chamada de 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) { }
      }
  }

  A falha:no Edge para nuvem privada 4.53.x, isso é executado sem problemas. Depois que o nó é atualizado para o Edge para nuvem privada 4.54.00, esse proxy falha imediatamente durante o processamento da solicitação:

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

• Após a correção (compatível com o Edge para nuvem privada 4.53.x e 4.54.00): não é necessário reescrever ou recompilar o código da chamada de Java. É possível tornar o proxy compatível com as duas versões fornecendo os JARs independentes:
  1. Agrupe ou faça upload diretamente dos JARs independentes:consiga as bibliotecas JAXB independentes (jakarta.xml.bind-api-2.3.3.jar e jaxb-runtime-2.3.8.jar) e coloque-as no pacote de proxy em apiproxy/resources/java/:

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

     Como alternativa, faça upload de jakarta.xml.bind-api-2.3.3.jar e jaxb-runtime-2.3.8.jar como arquivos de recursos usando a API Resource Files no nível do proxy, no nível do ambiente ou no nível da organização para que todos os proxies no mesmo escopo possam compartilhá-los sem agrupá-los em cada pacote de proxy individual.

     Se você criar o pacote de proxy da origem usando o Maven, declare essas dependências no pom.xml para que elas sejam empacotadas automaticamente durante o build.

  2. Implante e teste no cluster 4.53.x atual:implante o pacote de proxy atualizado no ambiente atual do Edge para nuvem privada 4.53.x e envie chamadas de teste. Como os processadores de mensagens do Edge para nuvem privada 4.53.x carregam classes desses JARs agrupados, é possível verificar se a chamada continua funcionando de maneira idêntica.
  3. Ative o carregamento de pacotes externos permitidos pelo CwC:como o carregamento de pacotes externos permitidos está desativado por padrão no Edge para nuvem privada 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false), ative-o em cada nó do processador de mensagens em /opt/apigee/customer/application/message-processor.properties usando o código com configuração (CwC):

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

  4. Zero problemas de tráfego em tempo real após o upgrade:depois de validado no ambiente 4.53.x e configurado com a propriedade CwC, seu proxy estará totalmente preparado. Quando você faz upgrade do cluster para o Edge para nuvem privada 4.54.00, o processador de mensagens carrega as classes JAXB incluídas, garantindo zero erros e zero interrupção do tráfego em tempo real.

Estratégia 2: implementação alternativa (modernização de código e dependência)

Quando usar:recomendado para bases de código ativas em que o código-fonte do proxy é mantido com facilidade. Essa é a abordagem de longo prazo mais limpa para conformidade com o Java 21. Observação sobre o lançamento:como a implantação de revisões de proxy modernizadas requer a coordenação do processador de mensagens, combine essa estratégia com a Estratégia 3A (durante uma janela de manutenção planejada) ou com a Estratégia 3B (para alcançar zero inatividade com processadores de mensagens paralelos).

Como funciona:substitua as classes internas do Java removidas por APIs Java SE padrão oficiais ou equivalentes independentes de código aberto e empacote as dependências de terceiros necessárias diretamente nos arquivos de recursos do pacote de proxy ou no POM.

Exemplos de código:

Exemplo 1: modernização de métodos e códigos (substituição de utilitários internos removidos)

No Java 8, as chamadas usavam com frequência classes de utilitários internos, como sun.misc.BASE64Encoder. No Java moderno, essas classes foram removidas, mas a API java.util.Base64 padrão oferece substituições diretas sem exigir JARs de dependência externa:

• Antes (implementação legada do 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;
      }
  }

• Depois (implementação compatível com 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;
      }
  }

Exemplo 2: refatoração no nível de importação com biblioteca em pacote (mapeador de prefixo de namespace JAXB)

No Java 8, os proxies de API que personalizam prefixos de namespace XML geralmente estendiam o mapeador JAXB interno da Sun com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. No Java 21, os pacotes internos da Sun são removidos e ficam inacessíveis.

A biblioteca de código aberto independente (org.glassfish.jaxb:jaxb-runtime) fornece a classe idêntica em com.sun.xml.bind.marshaller.NamespacePrefixMapper. Todas as assinaturas de método, parâmetros e tipos de retorno são idênticos. A mudança de código é estritamente na instrução de importação:

• Antes (implementação legada do 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;
      }
  }

• Depois (implementação compatível com 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;
      }
  }

• Configuração de dependência em pacote (pom.xml): para fornecer essa classe no ambiente de execução, agrupe as bibliotecas JAXB independentes em apiproxy/resources/java/ ou declare-as em 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>

Estratégia 3A: inatividade por manutenção planejada (reimplantação no local)

Quando usar:recomendado para ambientes com janelas de manutenção operacional programadas em que uma breve interrupção do serviço é aceitável.

Procedimento:

1. Coordenar uma janela de manutenção programada com os consumidores da API.
2. Faça upgrade dos componentes do Edge para nuvem privada para a versão 4.54.00 seguindo o guia de caminhos de upgrade.
3. Implante a revisão pré-compilada e compatível com a versão 4.54.00 do proxy de API usando a nova interface do Edge ou a API Apigee Management (implantações).
4. Verifique a execução da chamada enviando solicitações de teste sintéticas para os processadores de mensagens e inspecionando os registros usando a ferramenta Trace.
5. Feche a janela de manutenção e reabra o tráfego público.

Estratégia 3B: criar um novo ambiente (migração sem inatividade)

Quando usar:recomendado para ambientes de produção essenciais que exigem zero inatividade. Use essa opção quando a chamada de Java não puder ser atualizada para funcionar no Java 8 e no Java 21 simultaneamente.

Como funciona:essa estratégia envolve a aquisição de um ou mais ambientes novos para que você possa conectar nós do processador de mensagens de versões diferentes a ele. Em seguida, implante proxies compatíveis com o Java 8 no ambiente conectado com processadores de mensagens 4.53.X e proxies compatíveis com o Java 21 no ambiente conectado com processadores de mensagens 4.54.00. Em seguida, use um balanceador de carga ou outras técnicas de roteamento para direcionar o tráfego apenas para o proxy compatível com o Java 21.

Para essa estratégia, entender como as organizações, os ambientes e os processadores de mensagens interagem é fundamental para uma transição sem inatividade (para mais informações, consulte Estrutura da organização da Apigee Edge):

• Uma organização da Apigee é um limite administrativo de nível superior que contém vários ambientes (por exemplo, prod, test).
• Uma revisão de proxy de API é implantada em um ambiente específico. Somente os processadores de mensagens explicitamente vinculados a esse ambiente carregam e executam a revisão do 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        |
          +------------------------------------------------------+

Procedimento:

1. Crie um ambiente temporário:crie um novo ambiente (por exemplo, prod-migration) na sua organização (seguindo as instruções em Como configurar hosts e ambientes virtuais) com um host virtual e uma porta dedicados.
2. Provisionar nós do processador de mensagens 4.54.00:instale o Edge para nuvem privada 4.54.00 em instâncias de VM novas ou temporárias e vincule esses nós a prod-migration (consulte Como adicionar um processador de mensagens).
3. Identificar proxies afetados e criar revisões atualizadas:identifique proxies de API que usam chamadas de Java (com a ferramenta de detecção de mudanças) e crie uma nova revisão de cada proxy afetado com chamadas de Java compatíveis com o Edge para nuvem privada 4.54.00 (aplicando a Estratégia 1 ou a Estratégia 2).
4. Implantar revisões de proxy modernizadas no ambiente temporário:implante as revisões de proxy atualizadas e compatíveis exclusivamente em prod-migration.
5. Verificar e mudar o tráfego:execute testes de verificação sintéticos no novo host virtual. Depois de verificado, configure o balanceador de carga externo (F5, NGINX) para redirecionar o tráfego do cliente de prod para prod-migration.
6. Faça upgrade dos nós originais e volte para o estado anterior:cancele a implantação dos proxies legados de prod. Faça upgrade dos nós originais do processador de mensagens para a versão 4.54.00 seguindo o guia de caminhos de upgrade. Implante as revisões de proxy modernizadas no prod, redirecione o tráfego do balanceador de carga de volta para o prod e verifique a operação.
7. Desativar o ambiente temporário:cancele a implantação de proxies de prod-migration, remova os nós temporários do processador de mensagens e exclua o ambiente temporário.

Estratégia 3C: posicionamento de biblioteca externa no nível do nó (bibliotecas de substituição compartilhadas)

Quando usar:recomendado quando você tem vários proxies de API que dependem de classes Java que foram removidas no Java 21, e a recompilação ou o reempacotamento de cada pacote de proxy individual antes do upgrade é operacionalmente inviável.

Como funciona:no Edge para nuvem privada 4.54.00, os processadores de mensagens fornecem um mecanismo para carregar classes Java ausentes de um diretório de nó dedicado: $APIGEE_ROOT/data/edge-message-processor/external-lib.

Quando esse mecanismo está ativado, o processador de mensagens verifica se há classes ausentes nesse diretório antes de voltar à resolução padrão. Para fornecer as classes que faltam, use JARs de bibliotecas de terceiros ou agrupe as classes necessárias em um JAR e coloque-o em external-lib.

Procedimento:

1. Crie o diretório da biblioteca externa em cada nó do processador de mensagens:

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

2. Coloque os JARs necessários no diretório:copie os arquivos JAR que contêm as classes necessárias para /opt/apigee/data/edge-message-processor/external-lib.
3. Defina as permissões de arquivo adequadas:verifique se o usuário de serviço apigee tem permissões de leitura:

   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. Ative o carregamento de pacotes externos na configuração do processador de mensagens:por padrão, no Edge para nuvem privada 4.54.00, o carregamento de pacotes externos permitidos está desativado (conf_system_java.21.enable.external.allowed.packages=false). Para permitir que o processador de mensagens resolva e carregue classes de /opt/apigee/data/edge-message-processor/external-lib, ative essa propriedade em /opt/apigee/customer/application/message-processor.properties usando o código com configuração (CwC):

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

5. Reinicie o processador de mensagens:

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

Estratégia 4: flags da JVM (--add-opens / --add-exports — cuidado e último recurso)

Quando usar:use essa estratégia como último recurso para bibliotecas de fornecedores terceirizados de software proprietário em que o código-fonte não está disponível, os fornecedores não lançaram atualizações do Java 21 e o JAR depende estritamente do acesso reflexivo a pacotes Java internos.

Procedimento:

1. Identifique o pacote inacessível usado para reflexão:determine o módulo e o pacote internos do Java acessados de forma reflexiva pela biblioteca de terceiros. Observação:esses erros de reflexão ocorrem estritamente no Java 21 no Edge para nuvem privada 4.54.00 e não aparecem nos registros da versão 4.53.x. Verifique os registros do processador de mensagens (/opt/apigee/var/log/edge-message-processor/system.log) após o upgrade para o InaccessibleObjectException que identifica o módulo e o pacote necessários:

   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. Edite /opt/apigee/customer/application/message-processor.properties usando o código com configuração (CwC) (crie o arquivo se ele não existir).
3. Anexe as flags --add-opens ou --add-exports segmentadas 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. Verifique se a propriedade e as permissões do arquivo estão corretas:

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

5. Reinicie o processador de mensagens usando apigee-service:

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

Mudanças no TLS e no pacote de criptografia

No Edge para nuvem privada 4.54.00, os principais componentes da plataforma, incluindo o processador de mensagens, o servidor de gerenciamento e o roteador, foram atualizados para serem executados no Java 21 LTS. Esta atualização moderniza a segurança criptográfica ao ativar o TLS 1.3 por padrão (JEP 332). Os processadores de mensagens agora negociam o TLS 1.3 como o protocolo preferencial para conexões de back-end de saída, voltando para o TLS 1.2 quando o back-end não oferece suporte.

Requisitos e correção de back-end legados

A referência criptográfica do Java 21 atualiza a lista de protocolos e pacotes de criptografia desativados por padrão em jdk.tls.disabledAlgorithms (como protocolos TLS legados e pacotes de troca de chaves RSA estáticos sem forward secrecy: TLS_RSA_*). Como você fornece seu próprio ambiente de execução do Java 21, a lista exata de protocolos e pacotes de criptografia desativados depende da sua implementação específica do Java 21.

Se os proxies de API atuais se conectarem a uma infraestrutura de back-end legada que exige protocolos desativados ou criptografias RSA estáticas, confira as seguintes ações:

• Modernize a segurança do back-end (recomendado): faça upgrade dos servidores de destino e dos balanceadores de carga para que sejam compatíveis com o TLS 1.2 ou TLS 1.3 com pacotes de criptografia ECDHE modernos. Para configurar protocolos e pacotes de criptografia nos proxies de API, consulte Como configurar o TLS do Edge para o back-end e a referência de configuração do TargetEndpoint de TLS/SSL (ou Balanceamento de carga entre servidores de back-end se estiver usando TargetServers).
• Reativar algoritmos legados usando CwC (medida de transição durante o upgrade): se os upgrades de back-end não puderem ser concluídos antes do upgrade da plataforma, reative temporariamente os algoritmos necessários usando o código com configuração (CwC):
  1. Verifique o valor padrão de jdk.tls.disabledAlgorithms na instalação do Java 21 (por exemplo, em $JAVA_HOME/conf/security/java.security).
  2. Substitua conf_jvmsecurity_jdk.tls.disabledAlgorithms em /opt/apigee/customer/application/message-processor.properties pela mesma lista de algoritmos desativados, removendo apenas a entrada TLS_RSA_* (mantenha todos os outros algoritmos desativados intactos para que as proteções restantes permaneçam ativadas).
  3. Reinicie o processador de mensagens usando apigee-service. Remova essa substituição quando o back-end for compatível com pacotes de criptografia ECDHE.
• Atualizar uma lista de permissões de pacote de criptografia personalizado:se você tiver substituído conf_http_HTTPTransport.ssl.cipher.suites.whitelist, revise-o antes de fazer upgrade. O Java 21 não é mais compatível com os pacotes RSA estáticos (TLS_RSA_*). Portanto, uma lista de permissões que contém apenas esses pacotes deixa o processador de mensagens sem uma criptografia utilizável, e as chamadas de back-end falham com no cipher suites in common. Remova as entradas TLS_RSA_* e configure conjuntos de criptografia modernos compatíveis com sua implementação do Java 21. Se você não tiver substituído essa propriedade, os padrões da versão 4.54.00 já vão incluir os pacotes compatíveis, e nenhuma mudança será necessária.
• Atualizar as criptografias internas do roteador para o processador de mensagens:se você tiver substituído conf_message-processor-communication_local.http.ssl.ciphers por pacotes RSA estáticos, atualize-o com pacotes de criptografia modernos compatíveis com sua implementação do Java 21 antes de fazer upgrade. Caso contrário, o roteador não poderá concluir um handshake de TLS com o processador de mensagens. Em seguida, reinicie o processador de mensagens:

  apigee-service edge-message-processor restart

  Consulte Como configurar o TLS entre um roteador e um processador de mensagens.

Para detalhes sobre como configurar o TLS entre componentes do Edge, consulte Como configurar o TLS entre um roteador e um processador de mensagens.

Ferramenta de detecção de mudanças

A Apigee oferece uma ferramenta de detecção de mudanças para verificar se há proxies de API, políticas, fluxos compartilhados e JARs de recursos implantados no cluster que podem ser afetados pelo upgrade para o Edge para nuvem privada 4.54.00.

A ferramenta identifica possíveis bloqueadores de upgrade, incluindo bibliotecas incompatíveis com o Java 21, APIs internas fortemente encapsuladas, descontinuações de políticas legadas e limites de RDN do OpenLDAP, e produz relatórios úteis para ajudar você a selecionar estratégias de correção adequadas.

Para conferir todos os pré-requisitos, instruções de download, sintaxe de linha de comando e relatórios de amostra, consulte o guia dedicado à ferramenta de detecção de mudanças.