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

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

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

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

Изменения в правилах 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 достоверностью влияния, предлагая разработчикам проверить исходный код своих выносок на наличие измененных вызовов методов.

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

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

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

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

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

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

Требуется ли обновление и повторное развертывание пакета прокси-сервера? Сценарий или требование Рекомендуемая стратегия Что это дает Основные ограничения
Да (только обновление набора) Существует библиотека с двойной совместимостью; требуется нулевое время простоя Стратегия 1. Прокси-сервер с двойной совместимостью через пакетные JAR-файлы Восстанавливает отсутствующие библиотеки в разных версиях без простоев. Для этого должна быть доступна отдельная библиотека с поддержкой двух форматов, а в версии 4.54.00 должна быть включена функция conf_system_java.21.enable.external.allowed.packages=true.
Да (изменение исходного кода) Исходный код поддерживается; требуется долгосрочное исправление Стратегия 2. Альтернативная реализация (модернизация кода и зависимостей) Окончательно устраняет удаленные классы и внутренние зависимости API. Требует изменения исходного кода и повторного развертывания (в сочетании со стратегией 3A или 3B для развертывания)
Нет (операционный подход) Разрешенный период планового технического обслуживания Стратегия 3A: запланированное время простоя для технического обслуживания (переразвертывание на месте) Позволяет сначала обновить узел, а затем развернуть обновленный прокси-сервер. Требуется запланированное время простоя для пользователей API.
Нет (операционный подход) Не требуется время простоя; нельзя объединять двойные JAR-файлы Стратегия 3Б. Создание новой среды (перенос без простоев) Изолирует узлы версий 4.53 и 4.54 во время переноса без прерывания трафика Требуется приобрести временные узлы обработчика сообщений.
Нет (операционный подход) Нельзя изменить прокси-пакеты до обновления. * Стратегия 3C. Размещение внешней библиотеки на уровне узла Предоставляет отсутствующие JAR-файлы библиотек на уровне узла без редактирования пакетов прокси-серверов. Общий для всех прокси-серверов на узле; не решает проблему с пакетами reflection или java.*.
Нет (сторонние библиотеки с закрытым исходным кодом) Сторонние библиотеки, использующие рефлексию для внутренних компонентов Java * Стратегия 4. Флаги JVM (--add-opens / --add-exports) Смягчает ограничения на рефлексию для внутренних пакетов Java Невозможно восстановить удаленные классы или методы; применяется ко всему узлу.

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

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

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

Рассмотрим типичный вызов Apigee Java, который извлекает и проверяет входящие заказы в формате 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 для частного облака 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 и отправьте тестовые вызовы. Поскольку процессоры сообщений Edge для частного облака 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 для частного облака 4.54.00 процессор сообщений загружает встроенные классы 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 от Sun com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. В 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. Проверьте выполнение выносок, отправив синтетические тестовые запросы в процессоры сообщений и изучив журналы с помощью инструмента трассировки.
  5. Закройте перерыв на техническое обслуживание и снова откройте общедоступный трафик.

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

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

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

Чтобы переход на эту стратегию не привел к простою, необходимо понимать, как взаимодействуют организации, среды и процессоры сообщений (дополнительную информацию можно найти в статье Структура организации 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. Подготовьте узлы обработчика сообщений версии 4.54.00. Установите Edge для частного облака 4.54.00 на новые или временные экземпляры виртуальных машин и привяжите эти узлы к prod-migration (см. Добавление обработчика сообщений).
  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.

Если этот механизм включен, процессор сообщений проверяет этот каталог на наличие отсутствующих классов, прежде чем вернуться к разрешению по умолчанию. Вы можете предоставить недостающие классы, получив их из 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. Включите загрузку внешних пакетов в конфигурации обработчика сообщений. По умолчанию в Edge для частного облака 4.54.00 загрузка внешних разрешенных пакетов отключена (conf_system_java.21.enable.external.allowed.packages=false). Чтобы обработчик сообщений мог разрешать и загружать классы из /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. Перезапустите обработчик сообщений: 
    /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. Добавьте к директиве bin_setenv_ext_jvm_opts целевые флаги --add-opens или --add-exports. 
    # 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 (или Балансировка нагрузки между внутренними серверами, если используются TargetServer).
  • Повторно включите устаревшие алгоритмы с помощью 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 между маршрутизатором и процессором сообщений…

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

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

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

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

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