Zmiany w Edge dla chmury prywatnej w wersji 4.54.00

Omówienie zmian

Edge dla chmury prywatnej w wersji 4.54.00 wprowadza wiele zmian, które poprawiają stan zabezpieczeń platformy, i aktualizuje komponenty platformy, aby działały z Javą 21. Te zmiany opisujemy w 2 sekcjach poniżej:

• Zmiany w zasadach dotyczących wywołań Java
• Zmiany dotyczące TLS i zestawu szyfrów

Oprócz tych zmian zapoznaj się z dedykowanym przewodnikiem po narzędziu do wykrywania zmian. To narzędzie zostało udostępnione, aby umożliwić identyfikację zmian w serwerach proxy, przepływach współdzielonych lub innych artefaktach w klastrze, które mogą powodować zakłócenia w wyniku tego uaktualnienia.

Zmiany w zasadzie wywołania Javy

W Edge dla chmury prywatnej 4.54.00 podstawowe komponenty platformy, w tym procesor komunikatów, serwer zarządzania i router, są aktualizowane, aby działać na Java 21 LTS. Java 21 modernizuje platformę Java, co obejmuje usunięcie starszych modułów Java EE i CORBA (JEP 320), usunięcie starszych wewnętrznych klas narzędziowych i wymuszenie silnej enkapsulacji modułowej (JEP 403).

Z powodu tych zmian po uaktualnieniu do wersji 4.54.00 mogą wystąpić zakłócenia w działaniu serwerów proxy interfejsu API z niestandardowymi zasadami JavaCallout lub niestandardowymi plikami JAR zasobów (przechowywanymi na poziomie serwera proxy, środowiska lub organizacji).

Kategorie zmian, które mogą mieć wpływ na wywołania Javy

1. Trwale usunięte moduły Java EE i CORBA (JEP 320): moduły wcześniej wbudowane w środowisko wykonawcze Java 8 (w tym JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.* i CORBA org.omg.*) zostały usunięte z Java SE. Wywołania odwołujące się do tych pakietów bez dołączania samodzielnych zamienników kończą się niepowodzeniem w czasie działania z błędem NoClassDefFoundError.
2. Usunięto wewnętrzne klasy narzędziowe: usunięto starsze wewnętrzne klasy pomocnicze, takie jak sun.misc.BASE64Encoder i sun.misc.BASE64Decoder. Wywołania tych klas kończą się błędem NoClassDefFoundError.
3. Silne hermetyzowanie wewnętrznych elementów Javy (JEP 403): do wewnętrznych pakietów w java.base (takich jak sun.security.*, sun.reflect.* i com.sun.*) nie można uzyskać dostępu za pomocą odbicia z niestandardowych wywołań. Wywołania refleksyjne kończą się niepowodzeniem w czasie działania z błędem InaccessibleObjectException.
4. Zmiany i usunięcia sygnatur metod w zachowanych klasach Javy: w niektórych modułach Javy klasa pozostaje obecna w Java 21, ale określone konstruktory lub sygnatury metod zostały usunięte, wycofane lub zmienione (np. określone metody analizy DOM w org.w3c.dom.Document i powiązane klasy analizy XML).

   Wykrywanie narzędzi: narzędzie do wykrywania zmian oznacza odwołania do tych klas w kategorii METHOD_SIGNATURE_MODIFICATION jako MEDIUM Pewność wpływu, co zachęca deweloperów do sprawdzenia kodu źródłowego wywołań pod kątem zmodyfikowanych wywołań metod.

Strategie działań naprawczych

Zanim przejdziesz na wyższą wersję, upewnij się, że zasady wywołania Java i niestandardowe zasoby JAR są zgodne ze środowiskiem wykonawczym Java 21. Korzystanie z narzędzia do wykrywania zmian pomoże Ci zidentyfikować w klastrze serwery proxy interfejsów API, współdzielone przepływy i zasoby JAR środowiska lub organizacji, których dotyczy problem.

Strategie naprawcze opisane w tej sekcji są ogólnymi wskazówkami i nie wykluczają się wzajemnie. W zależności od wymagań operacyjnych możesz łączyć strategie – na przykład modernizować kod źródłowy wywołań za pomocą strategii 2 i wdrażać zaktualizowane wersje serwerów proxy za pomocą strategii 3B, aby uniknąć przestojów podczas uaktualniania procesora komunikatów.

Strategie 3A, 3B i 3C to 3 sposoby realizacji tego samego podejścia operacyjnego: uaktualnianie węzła i ponowne wdrażanie serwera proxy w różnych momentach bez zmiany pakietu serwera proxy. Wybierz jedną z tych opcji lub ich kombinację w zależności od wymagań dotyczących dostępności interfejsu API.

Zapoznaj się z poniższym przewodnikiem, aby wybrać najbardziej odpowiednie podejście do wdrożenia:

Przewodnik po decyzjach dotyczących rozwiązań problemów z wywołaniem Javy:

Strategia 1. Podwójnie zgodny serwer proxy z pakietami JAR (testowanie przed uaktualnieniem w celu zapewnienia zerowego czasu przestoju)

Kiedy warto z niej korzystać: używaj tej strategii, gdy:

• Dostępna jest samodzielna biblioteka zastępcza zgodna z obydwoma środowiskami: istnieje zastępczy plik JAR, który implementuje wymaganą funkcjonalność i może być dołączony bezpośrednio do serwera proxy interfejsu API bez konieczności modyfikowania kodu źródłowego.
• Chcesz, aby dotychczasowe serwery proxy interfejsu API i wywołania Javy działały bezproblemowo zarówno w obecnej wersji (np. Edge dla chmury prywatnej 4.53.01), jak i w uaktualnionej wersji (Edge dla chmury prywatnej 4.54.00).
• Chcesz przetestować i zweryfikować wszystkie zmiany w środowiskach testowym i produkcyjnym przed uaktualnieniem klastra Edge for Private Cloud, aby uniknąć nieoczekiwanych problemów i przestojów w przypadku ruchu na żywo.
• Chcesz uniknąć ponownego pisania lub refaktoryzacji logiki biznesowej wywołania Javy.

Jak to działa: w przypadku Javy 8 niektóre biblioteki (takie jak JAXB javax.xml.bind.* czy Activation javax.activation.*) były wbudowane bezpośrednio w środowisko wykonawcze Javy 8. Dzięki temu deweloperzy nie musieli dołączać dodatkowych plików JAR do pakietów proxy. W Javie 21 te biblioteki zostały usunięte ze środowiska wykonawczego Javy.

Aby zapewnić zgodność serwera proxy z Edge dla chmury prywatnej w wersji 4.53.x i 4.54.00:

1. Zidentyfikuj brakującą bibliotekę wymaganą przez wywołanie (np. JAXB lub Activation).
2. Pobierz samodzielny plik JAR typu open source (np. jakarta.xml.bind-api-2.3.3.jar i jaxb-runtime-2.3.8.jar).
3. Umieść zastępczy plik JAR bezpośrednio w pakiecie serwera proxy w apiproxy/resources/java/, prześlij go do wersji serwera proxy za pomocą interfejsu Resource Files API na poziomie serwera proxy lub prześlij go jako plik zasobów na poziomie środowiska lub poziomie organizacji. Więcej informacji o zarządzaniu plikami zasobów znajdziesz w dokumentacji plików zasobów Apigee.
4. Wdróż i przetestuj przed uaktualnieniem: procesory komunikatów w Edge dla chmury prywatnej w wersjach 4.53.x i 4.54.00 wczytują klasy z tych spakowanych plików JAR. Możesz teraz wdrożyć ten zaktualizowany pakiet proxy i przetestować go z ruchem syntetycznym w bieżącym klastrze Edge dla chmury prywatnej 4.53.x.
5. Włączanie ładowania zewnętrznych dozwolonych pakietów w procesorach komunikatów (wymagane w wersji 4.54.00): domyślnie w Edge dla chmury prywatnej w wersji 4.54.00 ładowanie usuniętych pakietów Java (takich jak javax.xml.bind.* i javax.activation.*) z zewnętrznych lub dołączonych plików JAR zasobów jest wyłączone (conf_system_java.21.enable.external.allowed.packages=false), więc samo dołączenie plików JAR nie będzie domyślnie działać. Musisz włączyć tę właściwość w /opt/apigee/customer/application/message-processor.properties, używając kodu z konfiguracją (CwC) (możesz skonfigurować tę właściwość przed uaktualnieniem węzła procesora komunikatów lub ustawić ją po uaktualnieniu i ponownie uruchomić procesor komunikatów):

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

6. Brak problemów z ruchem na żywo po uaktualnieniu: gdy klaster zostanie uaktualniony do Edge dla chmury prywatnej w wersji 4.54.00 z włączoną opcją conf_system_java.21.enable.external.allowed.packages=true, procesor komunikatów będzie już miał wymagany plik JAR i bez problemu załaduje klasy z dołączonego pliku zasobów (NoClassDefFoundError), co zapewni płynne uaktualnienie bez przestojów.

Przykład kodu: wywołanie weryfikacji i analizowania zamówienia w formacie XML

Rozważmy typowe wywołanie Javy w Apigee, które wyodrębnia i weryfikuje przychodzące zamówienia XML za pomocą JAXB (JAXBContext i Unmarshaller).

• Przed poprawką (błąd w Edge dla chmury prywatnej 4.54.00): w Edge dla chmury prywatnej 4.53.x pakiet serwera proxy zawiera tylko plik JAR wywołania, który korzysta z wbudowanych bibliotek środowiska wykonawczego Java 8 dla JAXB:

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

  Implementacja wywołania Javy:

  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) { }
      }
  }

  Błąd: w Edge dla chmury prywatnej w wersji 4.53.x to polecenie wykonuje się bez problemów. Gdy węzeł zostanie uaktualniony do Edge dla chmury prywatnej w wersji 4.54.00, ten serwer proxy natychmiast ulegnie awarii podczas przetwarzania żądania:

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

• Po wprowadzeniu poprawki (zgodność z Edge dla chmury prywatnej w wersji 4.53.x i 4.54.00): nie musisz ponownie pisać ani kompilować kodu wywołania Javy. Możesz bezpośrednio zapewnić zgodność serwera proxy z obydwoma protokołami, udostępniając samodzielne pliki JAR:
  1. Bezpośrednio połącz lub prześlij samodzielne pliki JAR: pobierz samodzielne biblioteki JAXB (jakarta.xml.bind-api-2.3.3.jar i jaxb-runtime-2.3.8.jar) i umieść je w pakiecie proxy w folderze apiproxy/resources/java/:

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

     Możesz też przesłać pliki jakarta.xml.bind-api-2.3.3.jar i jaxb-runtime-2.3.8.jar jako pliki zasobów za pomocą interfejsu Resource Files API na poziomie proxy lub na poziomie środowiska albo organizacji, aby wszystkie serwery proxy w tym samym zakresie mogły je udostępniać bez dołączania ich do każdego pakietu proxy.

     Jeśli tworzysz pakiet proxy ze źródła za pomocą Maven, zadeklaruj te zależności w pliku pom.xml, aby były automatycznie pakowane podczas kompilacji.

  2. Wdrażanie i testowanie w bieżącym klastrze 4.53.x: wdróż zaktualizowany pakiet serwerów proxy w istniejącym środowisku Edge dla chmury prywatnej 4.53.x i wyślij wywołania testowe. Ponieważ procesory komunikatów Edge dla chmury prywatnej w wersji 4.53.x wczytują klasy z tych dołączonych plików JAR, możesz sprawdzić, czy wywołanie nadal działa tak samo.
  3. Włączanie wczytywania zewnętrznych dozwolonych pakietów za pomocą CwC: ponieważ wczytywanie zewnętrznych dozwolonych pakietów jest domyślnie wyłączone w Edge dla chmury prywatnej 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false), włącz je w każdym węźle procesora komunikatów w /opt/apigee/customer/application/message-processor.properties za pomocą kodu z konfiguracją (CwC):

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

  4. Brak problemów z ruchem na żywo po uaktualnieniu: po zweryfikowaniu w środowisku 4.53.x i skonfigurowaniu z użyciem właściwości CwC serwer proxy jest w pełni przygotowany. Gdy uaktualnisz klaster do Edge dla chmury prywatnej 4.54.00, procesor komunikatów wczyta dołączone klasy JAXB, co zapewni brak błędów i brak zakłóceń w ruchu na żywo.

Strategia 2. Alternatywna implementacja (modernizacja kodu i zależności)

Kiedy używać: zalecane w przypadku aktywnych baz kodu, w których kod źródłowy serwera proxy jest łatwo dostępny. Jest to najczystsze długoterminowe podejście do zapewnienia zgodności z Java 21. Uwaga dotycząca wdrażania: wdrażanie zmodernizowanych wersji proxy wymaga koordynacji procesora komunikatów, dlatego połącz tę strategię ze strategią 3A (w zaplanowanym okresie konserwacji) lub strategią 3B (aby osiągnąć zerowy czas przestoju dzięki równoległym procesorom komunikatów).

Jak to działa: zastąp usunięte wewnętrzne klasy Java oficjalnymi standardowymi interfejsami Java SE API lub samodzielnymi odpowiednikami typu open source i spakuj wymagane zależności od firm zewnętrznych bezpośrednio w plikach zasobów pakietu proxy lub w POM.

Przykładowe kody:

Przykład 1. Modernizacja metody i kodu (zastępowanie usuniętych narzędzi wewnętrznych)

W Java 8 wywołania często korzystały z wewnętrznych klas narzędziowych, takich jak sun.misc.BASE64Encoder. W nowoczesnej Javie te klasy zostały usunięte, ale standardowy interfejs API java.util.Base64 zapewnia bezpośrednie zamienniki bez konieczności korzystania z zewnętrznych plików JAR zależności:

• Przed (starsza implementacja w 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;
      }
  }

• Po (implementacja zgodna z 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;
      }
  }

Przykład 2. Refaktoryzacja na poziomie importu z biblioteką w pakiecie (mapowanie prefiksów przestrzeni nazw JAXB)

W języku Java 8 serwery proxy interfejsu API dostosowujące prefiksy przestrzeni nazw XML zwykle rozszerzały wewnętrzny moduł mapujący JAXB firmy Sun com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. W Javie 21 wewnętrzne pakiety Sun są usunięte i niedostępne.

Samodzielna biblioteka open source (org.glassfish.jaxb:jaxb-runtime) udostępnia identyczną klasę w com.sun.xml.bind.marshaller.NamespacePrefixMapper. Wszystkie sygnatury metod, parametry i zwracane typy są identyczne – zmiana kodu dotyczy wyłącznie instrukcji importu:

• Przed (starsza implementacja 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;
      }
  }

• Po (implementacja zgodna z 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;
      }
  }

• Konfiguracja zależności w pakiecie (pom.xml): aby udostępnić tę klasę w czasie działania, umieść samodzielne biblioteki JAXB w pakiecie apiproxy/resources/java/ lub zadeklaruj je w pliku pom.xml:

  <dependencies>
      <!-- Standalone JAXB API for Java 21 -->
      <dependency>
          <groupId>jakarta.xml.bind</groupId>
          <artifactId>jakarta.xml.bind-api</artifactId>
          <version>2.3.3</version>
      </dependency>
      <!-- Standalone JAXB Runtime providing com.sun.xml.bind.marshaller.NamespacePrefixMapper -->
      <dependency>
          <groupId>org.glassfish.jaxb</groupId>
          <artifactId>jaxb-runtime</artifactId>
          <version>2.3.8</version>
      </dependency>
  </dependencies>

Strategia 3A: planowany przestój konserwacyjny (ponowne wdrożenie na miejscu)

Kiedy używać: zalecane w środowiskach z zaplanowanymi okresami konserwacji, w których dopuszczalne są krótkie przerwy w działaniu usługi.

Procedura:

1. Ustal z konsumentami interfejsu API zaplanowany okres konserwacji.
2. Zaktualizuj komponenty Edge dla chmury prywatnej do wersji 4.54.00 zgodnie z przewodnikiem po ścieżkach uaktualniania.
3. Wdróż wstępnie skompilowaną wersję serwera proxy interfejsu API zgodną z wersją 4.54.00 za pomocą nowego interfejsu Edge lub interfejsu Apigee Management API (Deployments).
4. Sprawdź, czy wywołanie jest wykonywane, wysyłając syntetyczne żądania testowe do procesorów komunikatów i sprawdzając logi za pomocą narzędzia do śledzenia.
5. Zamknij okno konserwacji i ponownie otwórz ruch publiczny.

Strategia 3B. Utwórz nowe środowisko (migracja bez przestoju)

Kiedy używać: zalecane w środowiskach produkcyjnych o kluczowym znaczeniu, które wymagają zerowego czasu przestoju. Użyj tej opcji, jeśli nie możesz zaktualizować wywołania Javy, aby działało jednocześnie w Javie 8 i Javie 21.

Jak to działa: ta strategia polega na pozyskaniu co najmniej 1 nowego środowiska, aby można było podłączyć do niego węzły procesora komunikatów w różnych wersjach. Następnie wdróż serwery proxy zgodne z Javą 8 w środowisku połączonym z procesorami komunikatów w wersji 4.53.X, a serwery proxy zgodne z Javą 21 w środowisku połączonym z procesorami komunikatów w wersji 4.54.00. Następnie użyj systemu równoważenia obciążenia lub innych technik kierowania ruchu, aby kierować ruch tylko do serwera proxy zgodnego z Java 21.

W przypadku tej strategii zrozumienie, jak organizacje, środowiska i procesory komunikatów współdziałają ze sobą, jest kluczem do przejścia na nowy system bez przestojów (więcej informacji znajdziesz w artykule o strukturze organizacji Apigee Edge):

• Organizacja Apigee to najwyższy poziom granicy administracyjnej, który zawiera wiele środowisk (np. prod, test).
• Wersja proxy interfejsu API jest wdrażana w konkretnym środowisku. Tylko procesory komunikatów, które są bezpośrednio powiązane z tym środowiskiem, wczytują i wykonują wersję serwera proxy.

+------------------------------------------------------------------------+
|                          Apigee Organization                           |
|                                                                        |
|  Existing Environment (prod)            Temporary Env (prod-migration) |
|  +--------------------------------+     +----------------------------+ |
|  | Current 4.53.01 MP Nodes       |     | New 4.54.00 MP Nodes       | |
|  |               |                |     |              |             | |
|  | Proxy Rev N (4.53.01)          |     | Proxy Rev N+1 (Modernized) | |
|  +--------------------------------+     +----------------------------+ |
+------------------------------------------------------------------------+
                   ^                                    ^
                   | Step 1: Normal Live                | Step 2: Canary
                   |         Traffic (prod)             | Step 3: Complete
          +------------------------------------------------------+
          |       Upstream Load Balancer / Ingress Router        |
          +------------------------------------------------------+

Procedura:

1. Utwórz środowisko tymczasowe: utwórz nowe środowisko (np. prod-migration) w organizacji (zgodnie z instrukcjami podanymi w artykule Konfigurowanie hostów wirtualnych i środowisk) z dedykowanym hostem wirtualnym i portem.
2. Zainicjuj węzły procesora komunikatów w wersji 4.54.00: zainstaluj Edge dla chmury prywatnej w wersji 4.54.00 na nowych lub tymczasowych instancjach maszyn wirtualnych i powiąż te węzły z prod-migration (patrz Dodawanie procesora komunikatów).
3. Zidentyfikuj serwery proxy, których dotyczy problem, i utwórz zaktualizowane wersje: zidentyfikuj serwery proxy interfejsu API korzystające z wywołań Javy (za pomocą narzędzia do wykrywania zmian) i utwórz nową wersję każdego serwera proxy, którego dotyczy problem, z wywołaniami Javy zgodnymi z Edge dla chmury prywatnej w wersji 4.54.00 (stosując strategię 1 lub strategię 2).
4. Wdrażanie zmodernizowanych wersji proxy w środowisku tymczasowym: wdrażaj zaktualizowane, zgodne wersje proxy wyłącznie w środowisku prod-migration.
5. Weryfikacja i przekierowanie ruchu: przeprowadź syntetyczne testy weryfikacyjne na nowym hoście wirtualnym. Po zweryfikowaniu skonfiguruj zewnętrzny system równoważenia obciążenia (F5, NGINX), aby przekierowywać ruch klientów z prod do prod-migration.
6. Uaktualnij pierwotne węzły i przełącz się z powrotem: wycofaj starsze serwery proxy z prod. Uaktualnij oryginalne węzły procesora komunikatów do wersji 4.54.00, korzystając z przewodnika po ścieżkach uaktualniania. Wdróż zmodernizowane wersje serwera proxy w środowisku prod, przekieruj ruch z systemu równoważenia obciążenia z powrotem do środowiska prod i sprawdź działanie.
7. Wycofaj środowisko tymczasowe: wycofaj wdrożenie serwerów proxy z prod-migration, usuń tymczasowe węzły procesora komunikatów i usuń środowisko tymczasowe.

Strategia 3C: umieszczanie bibliotek zewnętrznych na poziomie węzła (udostępnione biblioteki zastępcze)

Kiedy używać: zalecane, gdy masz wiele serwerów proxy interfejsu API korzystających z klas Java, które zostały usunięte w Java 21, a ponowne kompilowanie lub ponowne pakowanie każdego pakietu serwera proxy przed uaktualnieniem jest niewykonalne.

Jak to działa: w Edge dla chmury prywatnej w wersji 4.54.00 procesory komunikatów udostępniają mechanizm wczytywania brakujących klas Java z dedykowanego katalogu węzła: $APIGEE_ROOT/data/edge-message-processor/external-lib.

Gdy ten mechanizm jest włączony, procesor komunikatów sprawdza ten katalog pod kątem brakujących klas, zanim przejdzie do domyślnego rozwiązania. Brakujące klasy możesz udostępnić, pobierając je z plików JAR bibliotek innych firm lub pakując wymagane klasy do pliku JAR i umieszczając go w external-lib.

Procedura:

1. Utwórz katalog biblioteki zewnętrznej w każdym węźle procesora komunikatów:

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

2. Umieść wymagane pliki JAR w katalogu: skopiuj pliki JAR zawierające wymagane klasy do katalogu /opt/apigee/data/edge-message-processor/external-lib.
3. Ustaw odpowiednie uprawnienia do plików: upewnij się, że użytkownik usługi apigee ma uprawnienia do odczytu:

   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. Włącz ładowanie pakietów zewnętrznych w konfiguracji procesora komunikatów: domyślnie w Edge dla chmury prywatnej 4.54.00 ładowanie dozwolonych pakietów zewnętrznych jest wyłączone (conf_system_java.21.enable.external.allowed.packages=false). Aby umożliwić procesorowi komunikatów rozpoznawanie i ładowanie klas z /opt/apigee/data/edge-message-processor/external-lib, musisz włączyć tę właściwość w /opt/apigee/customer/application/message-processor.properties za pomocą kodu z konfiguracją (CwC):

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

5. Uruchom ponownie procesor komunikatów:

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

Strategia 4. Flagi JVM (--add-opens / --add-exports – ostrożnie i w ostateczności)

Kiedy używać: stosuj tę strategię jako ostatnią deskę ratunku w przypadku bibliotek innych firm o zamkniętym kodzie źródłowym, gdy kod źródłowy jest niedostępny, dostawcy nie opublikowali aktualizacji Javy 21, a plik JAR ściśle zależy od dostępu refleksyjnego do wewnętrznych pakietów Javy.

Procedura:

1. Zidentyfikuj niedostępny pakiet używany do refleksji: określ wewnętrzny moduł i pakiet Javy, do którego biblioteka zewnętrzna uzyskuje dostęp za pomocą refleksji. Uwaga: te błędy odbicia występują tylko w przypadku Javy 21 w Edge dla chmury prywatnej w wersji 4.54.00 i nie pojawiają się w dziennikach wersji 4.53.x. Po uaktualnieniu sprawdź logi procesora komunikatów (/opt/apigee/var/log/edge-message-processor/system.log) pod kątem InaccessibleObjectException, aby zidentyfikować wymagany moduł i pakiet:

   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. Edytuj plik /opt/apigee/customer/application/message-processor.properties za pomocą kodu z konfiguracją (CwC) (utwórz plik, jeśli nie istnieje).
3. Dołącz docelowe flagi --add-opens lub --add-exports do 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. Upewnij się, że masz odpowiednie uprawnienia i własność pliku:

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

5. Uruchom ponownie procesor komunikatów za pomocą apigee-service:

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

Zmiany dotyczące TLS i zestawu szyfrów

W Edge dla chmury prywatnej w wersji 4.54.00 podstawowe komponenty platformy, w tym procesor komunikatów, serwer zarządzania i router, zostały zaktualizowane, aby działały w Java 21 LTS. Ta aktualizacja unowocześnia zabezpieczenia kryptograficzne, ponieważ domyślnie włącza protokół TLS 1.3 (JEP 332). Procesory komunikatów negocjują teraz TLS 1.3 jako preferowany protokół dla wychodzących połączeń backendu, a jeśli backend go nie obsługuje, przechodzą na TLS 1.2.

Wymagania dotyczące starszego backendu i działania naprawcze

Podstawowe ustawienia kryptograficzne Javy 21 aktualizują listę protokołów i zestawów szyfrów wyłączonych domyślnie w jdk.tls.disabledAlgorithms (takich jak starsze protokoły TLS i zestawy statycznej wymiany kluczy RSA bez utajnienia przekazywania: TLS_RSA_*). Ponieważ dostarczasz własne środowisko wykonawcze Javy 21, dokładna lista wyłączonych protokołów i zestawów szyfrów zależy od konkretnej implementacji Javy 21.

Jeśli Twoje dotychczasowe serwery proxy interfejsu API łączą się ze starszą infrastrukturą backendu, która wymaga wyłączonych protokołów lub statycznych szyfrów RSA, zapoznaj się z tymi działaniami:

• Zmodernizuj zabezpieczenia backendu (zalecane): zaktualizuj serwery docelowe i usługi równoważenia obciążenia, aby obsługiwały protokoły TLS 1.2 lub TLS 1.3 z nowoczesnymi zestawami szyfrów ECDHE. Aby skonfigurować protokoły i zestawy szyfrów w serwerach proxy interfejsu API, zapoznaj się z artykułem Konfigurowanie protokołu TLS od Edge do backendu i dokumentacją konfiguracji TargetEndpoint TLS/SSL (lub Równoważenie obciążenia na serwerach backendu, jeśli używasz TargetServers).
• Ponowne włączanie starszych algorytmów za pomocą CwC (rozwiązanie tymczasowe podczas uaktualniania): jeśli uaktualnienia backendu nie można ukończyć przed uaktualnieniem platformy, możesz tymczasowo ponownie włączyć wymagane algorytmy za pomocą kodu z konfiguracją (CwC):
  1. Sprawdź domyślną wartość jdk.tls.disabledAlgorithms w instalacji Javy 21 (na przykład w $JAVA_HOME/conf/security/java.security).
  2. Zastąp conf_jvmsecurity_jdk.tls.disabledAlgorithms w /opt/apigee/customer/application/message-processor.properties tą samą listą wyłączonych algorytmów, usuwając tylko wpis TLS_RSA_* (pozostaw wszystkie inne wyłączone algorytmy bez zmian, aby pozostałe zabezpieczenia były nadal włączone).
  3. Ponownie uruchom procesor komunikatów za pomocą polecenia apigee-service. Usuń to zastąpienie, gdy backend będzie obsługiwać zestawy szyfrów ECDHE.
• Zaktualizuj niestandardową listę dozwolonych zestawów szyfrów: jeśli wcześniej zastąpiono conf_http_HTTPTransport.ssl.cipher.suites.whitelist, sprawdź to przed uaktualnieniem. Java 21 nie obsługuje już statycznych zestawów RSA (TLS_RSA_*), więc lista dozwolonych, która zawiera tylko te zestawy, pozostawia procesor komunikatów bez użytecznego mechanizmu szyfrowania, a wywołania backendu kończą się niepowodzeniem z błędem no cipher suites in common. Usuń wpisy TLS_RSA_* i skonfiguruj nowoczesne zestawy szyfrów obsługiwane przez implementację Java 21. Jeśli nie zastąpisz tej właściwości, domyślne ustawienia wersji 4.54.00 będą już zawierać obsługiwane pakiety i nie trzeba będzie wprowadzać żadnych zmian.
• Zaktualizuj szyfry wewnętrznego routera do procesora komunikatów: jeśli wcześniej zastąpiono conf_message-processor-communication_local.http.ssl.ciphers statycznymi pakietami RSA, przed uaktualnieniem zastąp je nowoczesnymi zestawami szyfrów obsługiwanymi przez implementację Java 21. W przeciwnym razie router nie będzie mógł przeprowadzić uzgadniania połączenia TLS z procesorem komunikatów. Następnie ponownie uruchom procesor komunikatów:

  apigee-service edge-message-processor restart

  Zobacz Konfigurowanie protokołu TLS między routerem a procesorem komunikatów.

Szczegółowe informacje o konfigurowaniu TLS między komponentami Edge znajdziesz w artykule Konfigurowanie TLS między routerem a procesorem komunikatów.

Narzędzie do wykrywania zmian

Apigee udostępnia narzędzie do wykrywania zmian, które skanuje klaster pod kątem wdrożonych proxy interfejsów API, zasad, przepływów współdzielonych i plików JAR zasobów, na które może mieć wpływ uaktualnienie do Edge dla chmury prywatnej w wersji 4.54.00.

Narzędzie identyfikuje potencjalne przeszkody w uaktualnieniu, w tym biblioteki niezgodne z Java 21, silnie enkapsulowane wewnętrzne interfejsy API, wycofane starsze zasady i limity RDN OpenLDAP, i generuje raporty, które pomogą Ci wybrać odpowiednie strategie naprawcze.

Pełne wymagania wstępne, instrukcje pobierania, składnię wiersza poleceń i przykładowe raporty znajdziesz w przewodniku po narzędziu do wykrywania zmian.