Изменения в Edge для частного облака 4.54.00

Обзор изменений

В Edge for Private Cloud 4.54.00 внесены изменения, которые повышают безопасность платформы и обновляют ее компоненты для работы с Java 21. Эти изменения описаны в двух разделах ниже:

• Изменения в правилах Java Callout
• Изменения в TLS и наборе шифров

Помимо этих изменений, ознакомьтесь со специальным руководством по инструменту обнаружения изменений. Этот инструмент позволяет выявить изменения в прокси-серверах, общих потоках и других артефактах в кластере, которые могут вызвать сбои в результате обновления.

Три возможности, доступные в версии 4.53.01, не поддерживаются в Edge для Private Cloud 4.54.00. Прежде чем планировать обновление, ознакомьтесь с разделом Функции, не поддерживаемые в версии 4.54.00.

Функции, не поддерживаемые в версии 4.54.00

Edge for Private Cloud 4.54.00 не поддерживает следующие возможности, доступные в версии 4.53.01. Если в вашем развертывании используется какой-либо из них, не обновляйте его до версии 4.54.00. Оставайтесь на версии 4.53.01 и обратитесь в службу поддержки Apigee.

• Установка в изолированной среде Google Distributed Cloud (GDC). Edge for Private Cloud 4.54.00 не сертифицирован для изолированных сред GDC. Инструкции для версии 4.53.01 приведены в статье Как установить Apigee в изолированной среде Google Distributed Cloud.
• RHEL 8.X или Rocky 8.X с включенным FIPS. Edge for Private Cloud 4.54.00 не поддерживает установку на хосте RHEL 8.X или Rocky 8.X с включенным FIPS. Эти операционные системы поддерживаются, если режим FIPS не включен. В разделах, посвященных настройке версии 4.54.00, также отсутствуют инструкции по FIPS, которые есть в версии 4.53.01, в том числе по подготовке хранилища ключей BCFKS, свойству автоматической настройки FIPS_OS и настройке хранилища ключей PKCS12. Инструкции для версии 4.53.01 приведены в статье Edge for Private Cloud on FIPS-enabled RHEL 8.X or Rocky 8.X.
• Интеграция с аппаратным модулем безопасности (HSM). Edge for Private Cloud 4.54.00 не поддерживает исходящие TLS-подключения от Message Processor к целевым сервисам бэкенда, использующим сетевой HSM Entrust nShield. Инструкции для версии 4.53.01 приведены в руководстве по интеграции аппаратного модуля безопасности Southbound для Apigee Edge для частного облака.

Изменения в правилах Java Callout

В Edge for Private Cloud 4.54.00 основные компоненты платформы, включая Message Processor, Management Server и Router, обновлены для работы на Java 21 LTS. Java 21 модернизирует платформу Java, в том числе удаляет устаревшие модули Java EE и CORBA (JEP 320), удаляет устаревшие внутренние служебные классы и обеспечивает строгую модульную инкапсуляцию (JEP 403).

Из-за этих изменений прокси-серверы API с пользовательскими правилами JavaCallout или пользовательскими JAR-файлами ресурсов (хранящимися на уровне прокси-сервера, среды или организации) могут работать со сбоями после обновления до версии 4.54.00.

Категории изменений, которые могут повлиять на вызовы Java

1. Модули Java EE и CORBA удалены навсегда (JEP 320). Модули, ранее встроенные в среду выполнения Java 8 (включая JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.* и CORBA org.omg.*), удалены из Java SE. Вызовы, ссылающиеся на эти пакеты без включения автономных замен, завершаются ошибкой NoClassDefFoundError во время выполнения.
2. Удалены внутренние служебные классы. Удалены устаревшие внутренние вспомогательные классы, такие как sun.misc.BASE64Encoder и sun.misc.BASE64Decoder. Вызовы этих классов завершаются ошибкой NoClassDefFoundError.
3. Строгая инкапсуляция внутренних компонентов Java (JEP 403). Внутренние пакеты в java.base (например, sun.security.*, sun.reflect.* и com.sun.*) недоступны для рефлексии из пользовательских выносок. Рефлексивные вызовы завершаются ошибкой InaccessibleObjectException.
4. Изменение и удаление сигнатур методов в сохранившихся классах Java. В некоторых модулях Java класс присутствует в Java 21, но определенные конструкторы или сигнатуры методов были удалены, объявлены устаревшими или изменены (например, определенные методы синтаксического анализа DOM в org.w3c.dom.Document и связанных классах синтаксического анализа XML).

   Обнаружение изменений. Инструмент помечает ссылки на эти классы в категории METHOD_SIGNATURE_MODIFICATION как MEDIUM Impact Certainty, предлагая разработчикам проверить исходный код выносок на наличие измененных вызовов методов.

Стратегии устранения уязвимостей

Перед обновлением убедитесь, что ваши правила Java Callout и пользовательские ресурсы JAR совместимы со средой выполнения Java 21. Инструмент обнаружения изменений поможет вам определить, какие прокси-серверы API, общие потоки и ресурсы JAR среды или организации в кластере затронуты.

Описанные в этом разделе стратегии устранения проблем являются общими рекомендациями и не исключают друг друга. В зависимости от ваших операционных требований вы можете комбинировать стратегии. Например, можно модернизировать исходный код вызова, используя стратегию 2, и развернуть обновленные версии прокси-серверов, используя стратегию 3Б, чтобы избежать простоев во время обновления Message Processor.

Стратегии 3A, 3B и 3C – это три способа реализации одного и того же операционного подхода: обновление узла и повторное развертывание прокси-сервера в разное время без изменения пакета прокси-сервера. Выберите один или несколько вариантов в зависимости от требований к доступности API.

Чтобы выбрать наиболее подходящий подход к развертыванию, ознакомьтесь со следующими рекомендациями:

Руководство по выбору мер защиты для вызовов Java:

Стратегия 1. Прокси-сервер с двойной совместимостью через пакетные JAR-файлы (тестирование перед обновлением для нулевого времени простоя)

Когда использовать. Используйте эту стратегию, если:

• Доступна автономная библиотека с двойной совместимостью. Существует заменяющий JAR-файл, который реализует необходимую функциональность и может быть включен непосредственно в прокси-сервер API без изменения исходного кода.
• Вы хотите, чтобы существующие прокси-серверы API и вызовы Java без проблем работали как в текущей версии (например, Edge для частного облака 4.53.01), так и в обновленной версии (Edge для частного облака 4.54.00).
• Вы хотите протестировать и проверить все изменения в промежуточной и рабочей средах до обновления кластера Edge for Private Cloud, чтобы избежать непредвиденных проблем и простоев в работе.
• Вы хотите избежать переписывания или рефакторинга бизнес-логики Java Callout.

Как это работает. В Java 8 некоторые библиотеки (например, JAXB javax.xml.bind.* или Activation javax.activation.*) были встроены непосредственно в среду выполнения Java 8. Поэтому разработчикам не нужно было включать дополнительные JAR-файлы в пакеты прокси. В Java 21 эти библиотеки были удалены из среды выполнения Java.

Чтобы сделать прокси-сервер совместимым с Edge для Private Cloud 4.53.x и 4.54.00:

1. Определите, какая библиотека отсутствует (например, JAXB или Activation).
2. Получите отдельный JAR-файл с открытым исходным кодом, который заменит существующий (например, jakarta.xml.bind-api-2.3.3.jar и jaxb-runtime-2.3.8.jar).
3. Поместите JAR-файл непосредственно в пакет прокси-сервера в папку apiproxy/resources/java/, загрузите его в версию прокси-сервера с помощью API файлов ресурсов на уровне прокси-сервера или загрузите его как файл ресурсов на уровне среды или уровне организации. Подробную информацию об управлении файлами ресурсов можно найти в документации по файлам ресурсов Apigee.
4. Разверните и протестируйте перед обновлением. Message Processor в Edge для Private Cloud 4.53.x и 4.54.00 загружает классы из этих пакетов JAR. Вы можете развернуть этот обновленный пакет прокси-сервера и протестировать его с синтетическим трафиком в текущем кластере Edge for Private Cloud 4.53.x.
5. Разрешите загрузку внешних разрешенных пакетов в Message Processor (требуется для версии 4.54.00). По умолчанию в Edge для Private Cloud 4.54.00 загрузка удаленных пакетов Java (таких как javax.xml.bind.* и javax.activation.*) из внешних или связанных JAR-файлов ресурсов отключена (conf_system_java.21.enable.external.allowed.packages=false), поэтому связывание только JAR-файлов по умолчанию не будет работать. Это свойство необходимо включить в /opt/apigee/customer/application/message-processor.properties с помощью кода с конфигурацией (CwC). Вы можете настроить это свойство до обновления узла Message Processor или задать его после обновления и перезапустить Message Processor.

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

6. Отсутствие проблем с трафиком после обновления. Когда кластер будет обновлен до Edge for Private Cloud 4.54.00 с включенным параметром conf_system_java.21.enable.external.allowed.packages=true, у Message Processor уже будет нужный JAR-файл, и он загрузит классы из упакованного файла ресурсов без сбоев (NoClassDefFoundError). Это обеспечит плавное обновление без простоев.

Пример кода: проверка XML-файла заказа и вызов синтаксического анализа

Рассмотрим типичный вызов Java в Apigee, который извлекает и проверяет входящие заказы XML с помощью JAXB (JAXBContext и Unmarshaller).

• До исправления (ошибка в Edge for Private Cloud 4.54.00). В Edge for Private Cloud 4.53.x пакет прокси содержит только JAR-файл выноски, полагаясь на встроенные библиотеки среды выполнения Java 8 для JAXB:

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

  Реализация вызова 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) { }
      }
  }

  Сбой. В Edge для Private Cloud 4.53.x это выполняется без проблем. После обновления узла до Edge for Private Cloud 4.54.00 этот прокси-сервер сразу же дает сбой во время обработки запроса:

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

• После исправления (совместимость с Edge для Private Cloud 4.53.x и 4.54.00): вам не нужно переписывать или перекомпилировать код Java Callout. Вы можете напрямую обеспечить совместимость прокси-сервера с обеими версиями, предоставив отдельные JAR-файлы:
  1. Добавьте в пакет или загрузите отдельные JAR-файлы. Получите отдельные библиотеки JAXB (jakarta.xml.bind-api-2.3.3.jar и jaxb-runtime-2.3.8.jar) и поместите их в пакет прокси-сервера в папку apiproxy/resources/java/.

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

     Вы также можете загрузить файлы jakarta.xml.bind-api-2.3.3.jar и jaxb-runtime-2.3.8.jar как файлы ресурсов с помощью Resource Files API на уровне прокси-сервера, на уровне среды или на уровне организации, чтобы все прокси-серверы в одной области могли использовать их, не объединяя их в каждый отдельный пакет прокси-сервера.

     Если вы создаете пакет прокси из источника с помощью Maven, объявите эти зависимости в файле pom.xml, чтобы они автоматически упаковывались во время сборки.

  2. Разверните и протестируйте пакет в текущем кластере 4.53.x. Разверните обновленный пакет прокси-сервера в существующей среде Edge для Private Cloud 4.53.x и отправьте тестовые вызовы. Поскольку Message Processor в Edge for Private Cloud 4.53.x загружает классы из этих JAR-файлов, вы можете убедиться, что вызов продолжает работать так же.
  3. Включите загрузку внешних разрешенных пакетов с помощью CwC. Поскольку загрузка внешних разрешенных пакетов по умолчанию отключена в Edge для Private Cloud 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false), включите ее на каждом узле Message Processor в /opt/apigee/customer/application/message-processor.properties с помощью кода с конфигурацией (CwC):

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

  4. Отсутствие проблем с трафиком после обновления. После проверки в среде 4.53.x и настройки свойства CwC ваш прокси-сервер будет полностью готов к работе. При обновлении кластера до Edge for Private Cloud 4.54.00 Message Processor загружает пакетные классы JAXB, обеспечивая нулевое количество ошибок и нулевое прерывание трафика.

Стратегия 2. Альтернативная реализация (модернизация кода и зависимостей)

Когда использовать. Рекомендуется для активных баз кода, в которых легко поддерживать исходный код прокси-сервера. Это самый простой способ обеспечить соответствие требованиям Java 21 в долгосрочной перспективе. Примечание о развертывании. Поскольку для развертывания модернизированных версий прокси-серверов требуется координация Message Processor, сочетайте эту стратегию со стратегией 3A (во время планового перерыва на техническое обслуживание) или стратегией 3B (чтобы добиться нулевого времени простоя с помощью параллельных Message Processor).

Как это работает. Замените удаленные внутренние классы Java официальными стандартными API Java SE или эквивалентными автономными решениями с открытым исходным кодом и упакуйте необходимые сторонние зависимости непосредственно в файлы ресурсов пакета прокси-сервера или POM.

Примеры кода:

Пример 1. Модернизация методов и кода (замена удаленных внутренних утилит)

В Java 8 в дополнительных вызовах часто использовались внутренние служебные классы, такие как sun.misc.BASE64Encoder. В современных версиях Java эти классы были удалены, но стандартный API java.util.Base64 предоставляет прямые замены, не требующие внешних JAR-файлов зависимостей:

• До (устаревшая реализация 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;
      }
  }

• После (реализация, совместимая с 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;
      }
  }

Пример 2. Рефакторинг на уровне импорта со встроенной библиотекой (JAXB Namespace Prefix Mapper)

В Java 8 прокси-серверы API, настраивающие префиксы пространства имен XML, обычно расширяли внутренний сопоставитель JAXB com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper от Sun. В Java 21 внутренние пакеты Sun удалены и недоступны.

Отдельная библиотека с открытым исходным кодом (org.glassfish.jaxb:jaxb-runtime) предоставляет идентичный класс в com.sun.xml.bind.marshaller.NamespacePrefixMapper. Все сигнатуры методов, параметры и типы возвращаемых значений идентичны. Изменения в коде касаются только оператора импорта.

• До (устаревшая реализация 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;
      }
  }

• После (реализация, совместимая с 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;
      }
  }

• Конфигурация зависимостей в пакете (pom.xml). Чтобы предоставить этот класс во время выполнения, добавьте в пакет автономные библиотеки JAXB в apiproxy/resources/java/ или объявите их в 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>

Стратегия 3А. Запланированное время простоя для технического обслуживания (повторное развертывание на месте)

Когда использовать. Рекомендуется для сред с запланированными перерывами на техническое обслуживание, когда допустимо кратковременное прерывание работы сервиса.

Процедура:

1. Согласуйте с пользователями API время планового технического обслуживания.
2. Обновите компоненты Edge для Private Cloud до версии 4.54.00, следуя руководству по обновлению.
3. Разверните предварительно скомпилированную версию прокси-сервера API, совместимую с версией 4.54.00, с помощью нового интерфейса Edge или Apigee Management API (Deployments).
4. Проверьте выполнение вызова, отправив синтетические тестовые запросы в Message Processor и проверив журналы с помощью инструмента Trace.
5. Завершите перерыв на техническое обслуживание и откройте доступ к сайту.

Стратегия 3Б. Создание новой среды (перенос без простоев)

Когда использовать. Рекомендуется для критически важных рабочих сред, требующих нулевого времени простоя. Используйте этот вариант, если вызов Java нельзя обновить для одновременной работы с Java 8 и Java 21.

Принцип работы. Эта стратегия предполагает закупку одной или нескольких новых сред, чтобы вы могли подключить к ней узлы Message Processor разных версий. Затем разверните прокси-серверы, совместимые с Java 8, в среде, подключенной к Message Processor версии 4.53.X, и прокси-серверы, совместимые с Java 21, в среде, подключенной к Message Processor версии 4.54.00. Затем используйте балансировщик нагрузки или другие методы маршрутизации, чтобы направлять трафик только на прокси-сервер, совместимый с Java 21.

Для этой стратегии понимание того, как взаимодействуют организации, среды и Message Processor, является ключом к переходу без простоев (дополнительную информацию см. в разделе Структура организации Apigee Edge):

• Организация Apigee – это административная граница верхнего уровня, содержащая несколько сред (например, prod, test).
• Версия прокси-сервера API развертывается в определенной среде. Только Message Processor, явно связанные с этой средой, загружают и выполняют версию прокси.

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

Процедура:

1. Создайте временную среду. Создайте новую среду (например, prod-migration) в своей организации (следуя инструкциям в статье Настройка виртуальных хостов и сред) с выделенным виртуальным хостом и портом.
2. Подготовьте узлы Message Processor версии 4.54.00. Установите Edge для Private Cloud версии 4.54.00 на новые или временные экземпляры виртуальных машин и привяжите эти узлы к prod-migration (см. раздел Добавление Message Processor).
3. Определите затронутые прокси-серверы и создайте обновленные версии. Определите прокси-серверы API, использующие вызовы Java (с помощью инструмента обнаружения изменений), и создайте новую версию каждого затронутого прокси-сервера с вызовами Java, совместимыми с Edge for Private Cloud 4.54.00 (применив Стратегию 1 или Стратегию 2).
4. Разверните модернизированные версии прокси-серверов во временной среде. Разверните обновленные совместимые версии прокси-серверов только в среде prod-migration.
5. Проверка и перенаправление трафика. Выполните синтетические проверочные тесты для нового виртуального хоста. После проверки настройте внешний балансировщик нагрузки (F5, NGINX) для перенаправления трафика клиентов с prod на prod-migration.
6. Обновите исходные узлы и переключитесь обратно. Отмените развертывание устаревших прокси-серверов из prod. Обновите исходные узлы Message Processor до версии 4.54.00, следуя руководству по путям обновления. Разверните модернизированные версии прокси-сервера в prod, перенаправьте трафик балансировщика нагрузки обратно в prod и проверьте работу.
7. Вывод временной среды из эксплуатации. Отмените развертывание прокси-серверов из prod-migration, удалите временные узлы Message Processor и удалите временную среду.

Стратегия 3В. Размещение внешней библиотеки на уровне узла (общие резервные библиотеки)

Когда использовать. Рекомендуется, если у вас есть несколько прокси-серверов API, которые используют классы Java, удаленные в Java 21, и перекомпилировать или перепаковать каждый отдельный пакет прокси-сервера перед обновлением невозможно.

Как это работает. В Edge for Private Cloud 4.54.00 Message Processor предоставляет механизм для загрузки отсутствующих классов Java из специального каталога узла: $APIGEE_ROOT/data/edge-message-processor/external-lib.

Если этот механизм включен, Message Processor проверяет этот каталог на наличие отсутствующих классов, прежде чем вернуться к разрешению по умолчанию. Вы можете предоставить недостающие классы, получив их из JAR-файлов сторонних библиотек или объединив необходимые классы в JAR-файл и поместив его в external-lib.

Процедура:

1. Создайте каталог внешней библиотеки на каждом узле Message Processor:

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

2. Поместите необходимые JAR-файлы в каталог. Скопируйте JAR-файлы, содержащие нужные классы, в каталог /opt/apigee/data/edge-message-processor/external-lib.
3. Установите соответствующие разрешения файла. Убедитесь, что у пользователя сервиса apigee есть разрешение на чтение:

   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. Включите загрузку внешних пакетов в конфигурации Message Processor. По умолчанию в Edge для Private Cloud 4.54.00 загрузка внешних разрешенных пакетов отключена (conf_system_java.21.enable.external.allowed.packages=false). Чтобы разрешить Message Processor распознавать и загружать классы из /opt/apigee/data/edge-message-processor/external-lib, необходимо включить это свойство в /opt/apigee/customer/application/message-processor.properties с помощью кода с конфигурацией (CwC):

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

5. Перезапустите Message Processor:

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

Стратегия 4. Флаги JVM (--add-opens / --add-exports — использовать с осторожностью и в крайнем случае)

Когда использовать. Используйте эту стратегию в крайнем случае для сторонних библиотек с закрытым исходным кодом, когда исходный код недоступен, поставщики не выпустили обновления Java 21, а JAR-файл строго зависит от рефлексивного доступа к внутренним пакетам Java.

Процедура:

1. Определите недоступный пакет, используемый для рефлексии. Выясните, к какому внутреннему модулю и пакету Java обращается сторонняя библиотека. Примечание. Эти ошибки рефлексии возникают только в Java 21 в Edge для Private Cloud 4.54.00 и не появляются в журналах версии 4.53.x. После обновления проверьте журналы Message Processor (/opt/apigee/var/log/edge-message-processor/system.log) на наличие InaccessibleObjectException, чтобы определить необходимый модуль и пакет:

   java.lang.reflect.InaccessibleObjectException: Unable to make field private final byte[] java.lang.String.value accessible: module java.base does not "opens java.lang" to unnamed module

2. Измените файл /opt/apigee/customer/application/message-processor.properties, используя код с конфигурацией (CwC). Если файла нет, создайте его.
3. Добавьте целевые флаги --add-opens или --add-exports в 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. Убедитесь, что у вас есть право собственности на файл и необходимые разрешения.

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

5. Перезапустите Message Processor с помощью apigee-service:

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

Изменения в TLS и наборе шифров

В Edge for Private Cloud 4.54.00 основные компоненты платформы, включая Message Processor, Management Server и Router, обновлены для работы на Java 21 LTS. Это обновление повышает криптографическую безопасность, включая TLS 1.3 по умолчанию (JEP 332). Теперь Message Processor согласовывают TLS 1.3 в качестве предпочтительного протокола для исходящих подключений к серверной части, возвращаясь к TLS 1.2, если серверная часть его не поддерживает.

Требования к устаревшим серверным компонентам и устранение неполадок

Базовый уровень криптографии Java 21 обновляет список протоколов и наборов шифров, отключенных по умолчанию в jdk.tls.disabledAlgorithms (например, устаревшие протоколы TLS и наборы статических ключей RSA без прямой секретности: TLS_RSA_*). Поскольку вы используете собственную среду выполнения Java 21, точный список отключенных протоколов и наборов шифров зависит от вашей реализации Java 21.

Если ваши существующие прокси-серверы API подключаются к устаревшей инфраструктуре бэкенда, для которой требуются отключенные протоколы или статические шифры RSA, ознакомьтесь со следующими действиями:

• Обновите систему безопасности серверной части (рекомендуется). Обновите целевые серверы и балансировщики нагрузки, чтобы они поддерживали TLS 1.2 или TLS 1.3 с современными наборами шифров ECDHE. Чтобы настроить протоколы и наборы шифров в прокси-серверах API, ознакомьтесь со статьями Настройка TLS от Edge до бэкенда и Справочник по настройке TargetEndpoint для TLS/SSL (или Балансировка нагрузки между бэкенд-серверами, если используются TargetServers).
• Повторно включите устаревшие алгоритмы с помощью CwC (временная мера во время обновления). Если обновление серверной части не удается завершить до обновления платформы, вы можете временно повторно включить необходимые алгоритмы с помощью кода с конфигурацией (CwC):
  1. Проверьте значение jdk.tls.disabledAlgorithms по умолчанию в установленной версии Java 21 (например, в $JAVA_HOME/conf/security/java.security).
  2. Переопределите conf_jvmsecurity_jdk.tls.disabledAlgorithms в /opt/apigee/customer/application/message-processor.properties с тем же списком отключенных алгоритмов, удалив только запись TLS_RSA_* (оставьте все остальные отключенные алгоритмы без изменений, чтобы остальные средства защиты оставались включенными).
  3. Перезапустите Message Processor с помощью apigee-service. Удалите это переопределение, когда серверная часть начнет поддерживать наборы шифров ECDHE.
• Обновите белый список наборов шифров. Если вы ранее переопределили conf_http_HTTPTransport.ssl.cipher.suites.whitelist, проверьте его перед обновлением. Java 21 больше не поддерживает статические наборы RSA (TLS_RSA_*), поэтому белый список, содержащий только эти наборы, оставляет Message Processor без пригодного для использования шифра, и вызовы бэкенда завершаются ошибкой no cipher suites in common. Удалите записи TLS_RSA_* и настройте современные наборы шифров, поддерживаемые вашей реализацией Java 21. Если вы не переопределяли это свойство, то в настройках по умолчанию для версии 4.54.00 уже есть поддерживаемые наборы шифров и ничего менять не нужно.
• Обновите шифры для связи между внутренним маршрутизатором и Message Processor. Если вы ранее переопределили conf_message-processor-communication_local.http.ssl.ciphers статическими наборами RSA, перед обновлением замените их современными наборами шифров, поддерживаемыми вашей реализацией Java 21. В противном случае маршрутизатор не сможет выполнить подтверждение TLS с Message Processor. Затем перезапустите Message Processor:

  apigee-service edge-message-processor restart

  Подробнее о том, как настроить TLS между маршрутизатором и Message Processor…

Подробные сведения о настройке TLS между компонентами Edge приведены в статье Настройка TLS между маршрутизатором и процессором сообщений.

Инструмент обнаружения изменений

В Apigee есть инструмент обнаружения изменений, который сканирует кластер на наличие развернутых прокси-серверов API, правил, общих потоков и JAR-файлов ресурсов, на которые может повлиять обновление до Edge for Private Cloud 4.54.00.

Инструмент выявляет потенциальные проблемы, которые могут помешать обновлению, в том числе несовместимые с Java 21 библиотеки, строго инкапсулированные внутренние API, устаревшие правила и ограничения OpenLDAP RDN, и создает отчеты с рекомендациями по выбору подходящих стратегий устранения неполадок.

Полный список требований, инструкции по скачиванию, синтаксис командной строки и примеры отчетов вы найдете в руководстве по инструменту Change Detection.