Perubahan di Edge for Private Cloud 4.54.00

Ringkasan perubahan

Edge for Private Cloud 4.54.00 memperkenalkan beberapa perubahan yang meningkatkan postur keamanan platform dan mengupdate komponen platform agar berjalan dengan Java 21. Dua bagian di bawah membahas perubahan ini:

• Perubahan kebijakan Java Callout
• Perubahan TLS dan cipher suite

Selain perubahan ini, tinjau Panduan alat deteksi perubahan khusus. Utilitas ini telah tersedia untuk mengidentifikasi perubahan pada proxy, alur bersama, atau artefak lain di cluster Anda yang dapat menyebabkan gangguan akibat upgrade ini.

Perubahan kebijakan Panggilan Java

Di Edge for Private Cloud 4.54.00, komponen platform inti—termasuk Message Processor, Management Server, dan Router—diupdate untuk berjalan di Java 21 LTS. Java 21 memodernisasi Platform Java, yang mencakup penghapusan modul Java EE dan CORBA lama (JEP 320), penghapusan class utilitas internal lama, dan penerapan enkapsulasi modular yang kuat (JEP 403).

Karena perubahan ini, proxy API dengan kebijakan JavaCallout kustom atau JAR resource kustom (yang disimpan di tingkat proxy, lingkungan, atau organisasi) dapat mengalami gangguan saat diupgrade ke versi 4.54.00.

Kategori perubahan yang dapat memengaruhi Pemanggilan Java

1. Modul Java EE dan CORBA dihapus secara permanen (JEP 320): Modul yang sebelumnya di-build ke dalam runtime Java 8 (termasuk JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.*, dan CORBA org.omg.*) dihapus dari Java SE. Info yang merujuk ke paket ini tanpa memaketkan pengganti mandiri akan gagal saat runtime dengan NoClassDefFoundError.
2. Class utilitas internal yang dihapus: Helper internal lama seperti sun.misc.BASE64Encoder dan sun.misc.BASE64Decoder telah dihapus. Pesan singkat yang memanggil class ini akan gagal dengan NoClassDefFoundError.
3. Enkapsulasi kuat internal Java (JEP 403): Paket internal di java.base (seperti sun.security.*, sun.reflect.*, dan com.sun.*) tidak dapat diakses secara reflektif dari info kustom. Panggilan reflektif gagal saat runtime dengan InaccessibleObjectException.
4. Perubahan dan penghapusan tanda tangan metode di class Java yang tetap ada: Di modul Java tertentu, class tetap ada di Java 21, tetapi konstruktor atau tanda tangan metode tertentu telah dihapus, tidak digunakan lagi, atau diubah (seperti metode penguraian DOM tertentu di org.w3c.dom.Document dan class penguraian XML terkait).

   Deteksi alat: Alat deteksi perubahan menandai referensi ke class ini dalam kategori METHOD_SIGNATURE_MODIFICATION dengan MEDIUM Kepastian Dampak, sehingga mendorong developer untuk memeriksa kode sumber anotasi mereka untuk pemanggilan metode yang diubah.

Strategi perbaikan

Sebelum melakukan upgrade, pastikan kebijakan Java Callout dan resource JAR kustom Anda kompatibel dengan runtime Java 21. Menggunakan alat deteksi perubahan akan membantu Anda mengidentifikasi proxy API, alur bersama, dan resource JAR lingkungan atau organisasi yang terpengaruh di seluruh cluster Anda.

Strategi perbaikan yang dijelaskan di bagian ini adalah panduan umum dan tidak saling eksklusif. Bergantung pada persyaratan operasional, Anda dapat menggabungkan strategi—misalnya, memodernisasi kode sumber teks promosi menggunakan Strategi 2 dan men-deploy revisi proxy yang telah diupdate menggunakan Strategi 3B untuk mencapai nol waktu henti selama upgrade Message Processor.

Strategi 3A, 3B, dan 3C adalah tiga cara untuk menjalankan pendekatan operasional yang sama: mengupgrade node dan men-deploy ulang proxy pada waktu yang berbeda, tanpa mengubah paket proxy. Pilih salah satu atau kombinasi dari opsi ini berdasarkan persyaratan ketersediaan API Anda.

Tinjau panduan keputusan berikut untuk memilih pendekatan yang paling sesuai untuk deployment Anda:

Panduan keputusan untuk mitigasi Pemanggilan Java:

Strategi 1: Proxy yang kompatibel ganda melalui JAR yang dipaketkan (Uji sebelum upgrade untuk periode nonaktif nol)

Kapan harus digunakan: Gunakan strategi ini jika:

• Library pengganti mandiri yang kompatibel ganda tersedia: JAR pengganti ada yang mengimplementasikan fungsi yang diperlukan dan dapat di-bundle langsung ke dalam proxy API Anda tanpa memerlukan modifikasi kode sumber.
• Anda ingin Proxy API dan Pemanggilan Java yang ada berfungsi dengan lancar di versi saat ini (misalnya, Edge for Private Cloud 4.53.01) dan versi yang diupgrade (Edge for Private Cloud 4.54.00).
• Anda ingin menguji dan memverifikasi semua perubahan di lingkungan staging dan lingkungan produksi sebelum mengupgrade cluster Edge for Private Cloud, sehingga memastikan tidak ada masalah yang tidak terduga dan tidak ada waktu non-operasional dalam traffic langsung.
• Anda ingin menghindari penulisan ulang atau refaktorisasi logika bisnis pemanggilan Java Anda.

Cara kerjanya: Di Java 8, library tertentu (seperti JAXB javax.xml.bind.* atau Activation javax.activation.*) di-build langsung ke dalam runtime Java 8. Oleh karena itu, developer tidak perlu menyertakan file JAR tambahan di dalam paket proxy mereka. Di Java 21, library ini dihapus dari runtime Java.

Agar proxy Anda "kompatibel ganda" di Edge for Private Cloud 4.53.x dan 4.54.00:

1. Identifikasi library yang tidak ada yang diperlukan oleh balon teks Anda (misalnya, JAXB atau Activation).
2. Dapatkan JAR pengganti open source mandiri (misalnya, jakarta.xml.bind-api-2.3.3.jar dan jaxb-runtime-2.3.8.jar).
3. Tempatkan JAR pengganti langsung ke dalam paket proxy di bagian apiproxy/resources/java/, atau upload ke revisi proxy menggunakan Resource Files API tingkat proxy, atau upload sebagai file resource di tingkat lingkungan atau tingkat organisasi. Untuk mengetahui informasi selengkapnya tentang cara mengelola file resource, lihat Dokumentasi file Resource Apigee.
4. Deploy dan uji sebelum upgrade: Message Processor di Edge for Private Cloud 4.53.x dan 4.54.00 memuat class dari JAR yang dipaketkan ini. Anda dapat men-deploy paket proxy yang telah diupdate ini dan mengujinya dengan traffic sintetis di cluster Edge for Private Cloud 4.53.x saat ini.
5. Aktifkan pemuatan paket eksternal yang diizinkan di Message Processor (Diperlukan untuk 4.54.00): Secara default di Edge for Private Cloud 4.54.00, pemuatan paket Java yang dihapus (seperti javax.xml.bind.* dan javax.activation.*) dari JAR resource eksternal atau yang dipaketkan dinonaktifkan (conf_system_java.21.enable.external.allowed.packages=false), sehingga memaketkan JAR saja tidak akan berfungsi secara default. Anda harus mengaktifkan properti ini di /opt/apigee/customer/application/message-processor.properties menggunakan kode dengan konfigurasi (CwC) (Anda dapat mengonfigurasi properti ini sebelum mengupgrade node Message Processor, atau menyetelnya setelah mengupgrade dan memulai ulang Message Processor):

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

6. Tidak ada masalah traffic langsung setelah upgrade: Saat cluster Anda diupgrade ke Edge for Private Cloud 4.54.00 dengan conf_system_java.21.enable.external.allowed.packages=true diaktifkan, Message Processor sudah memiliki JAR yang diperlukan dan memuat class dari file resource yang dipaketkan tanpa kegagalan (NoClassDefFoundError), sehingga memastikan upgrade yang lancar tanpa periode nonaktif.

Contoh kode: Info validasi dan penguraian XML pesanan

Pertimbangkan Pemanggilan Java Apigee standar yang mengekstrak dan memvalidasi pesanan XML yang masuk menggunakan JAXB (JAXBContext dan Unmarshaller).

• Sebelum perbaikan (Gagal di Edge untuk Private Cloud 4.54.00): Di Edge untuk Private Cloud 4.53.x, paket proxy hanya berisi JAR callout, yang mengandalkan library runtime Java 8 bawaan untuk JAXB:

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

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

  Kegagalan: Di Edge for Private Cloud 4.53.x, perintah ini dijalankan tanpa masalah. Setelah node diupgrade ke Edge for Private Cloud 4.54.00, proxy ini akan langsung gagal selama pemrosesan permintaan:

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

• Setelah perbaikan (Kompatibel ganda di Edge untuk Private Cloud 4.53.x dan 4.54.00): Anda tidak perlu menulis ulang atau mengompilasi ulang kode Java Callout. Anda dapat langsung membuat proxy Anda kompatibel ganda dengan menyediakan JAR mandiri:
  1. Bundel atau upload JAR mandiri secara langsung: Dapatkan library JAXB mandiri (jakarta.xml.bind-api-2.3.3.jar dan jaxb-runtime-2.3.8.jar) lalu tempatkan di dalam paket proxy Anda di apiproxy/resources/java/:

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

     Atau, upload jakarta.xml.bind-api-2.3.3.jar dan jaxb-runtime-2.3.8.jar sebagai file resource menggunakan Resource Files API tingkat proxy, atau di tingkat lingkungan atau tingkat organisasi sehingga semua proxy pada cakupan yang sama dapat membagikannya tanpa menggabungkannya ke dalam setiap paket proxy.

     Jika Anda mem-build paket proxy dari sumber menggunakan Maven, deklarasikan dependensi ini di pom.xml agar dipaketkan secara otomatis selama build.

  2. Deploy dan uji di cluster 4.53.x Anda saat ini: Deploy paket proxy yang telah diupdate ke lingkungan Edge for Private Cloud 4.53.x yang ada dan kirim panggilan pengujian. Karena Message Processor Edge for Private Cloud 4.53.x memuat class dari JAR yang dipaketkan ini, Anda dapat memverifikasi bahwa callout terus berfungsi secara identik.
  3. Aktifkan pemuatan paket eksternal yang diizinkan melalui CwC: Karena pemuatan paket eksternal yang diizinkan dinonaktifkan secara default di Edge for Private Cloud 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false), aktifkan di setiap node Message Processor di /opt/apigee/customer/application/message-processor.properties menggunakan code with config (CwC):

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

  4. Tidak ada masalah traffic langsung setelah upgrade: Setelah divalidasi di lingkungan 4.53.x dan dikonfigurasi dengan properti CwC, proxy Anda sepenuhnya siap. Saat Anda mengupgrade cluster ke Edge for Private Cloud 4.54.00, Message Processor akan memuat class JAXB yang dipaketkan, sehingga memastikan tidak ada error dan tidak ada gangguan traffic langsung.

Strategi 2: Penerapan alternatif (Modernisasi kode dan dependensi)

Kapan harus digunakan: Direkomendasikan untuk codebase aktif yang kode sumber proxynya mudah dikelola. Ini adalah pendekatan jangka panjang yang paling rapi untuk kepatuhan Java 21. Catatan peluncuran: Karena men-deploy revisi proxy yang dimodernisasi memerlukan koordinasi Message Processor, pasangkan strategi ini dengan Strategi 3A (selama masa pemeliharaan terencana) atau Strategi 3B (untuk mencapai periode nonaktif nol dengan Message Processor paralel).

Cara kerjanya: Ganti class internal Java yang dihapus dengan API Java SE standar resmi atau open source yang setara dan mandiri, serta paketkan dependensi pihak ketiga yang diperlukan langsung dalam file resource atau POM paket proxy Anda.

Contoh kode:

Contoh 1: Modernisasi metode dan kode (Mengganti utilitas internal yang dihapus)

Di Java 8, callout sering menggunakan class utilitas internal seperti sun.misc.BASE64Encoder. Di Java modern, class ini telah dihapus, tetapi java.util.Base64 API standar menyediakan pengganti langsung tanpa memerlukan JAR dependensi eksternal:

• Sebelumnya (Implementasi Java 8 lama):

  // 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;
      }
  }

• Setelah (penerapan yang kompatibel dengan 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;
      }
  }

Contoh 2: Refaktorisasi tingkat impor dengan library yang dipaketkan (JAXB Namespace Prefix Mapper)

Di Java 8, proxy API yang menyesuaikan awalan namespace XML biasanya memperluas pemeta JAXB internal Sun com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. Di Java 21, paket Sun internal dihapus dan tidak dapat diakses.

Library open source mandiri (org.glassfish.jaxb:jaxb-runtime) menyediakan class yang identik di bagian com.sun.xml.bind.marshaller.NamespacePrefixMapper. Semua tanda tangan metode, parameter, dan jenis nilai yang ditampilkan identik—perubahan kode hanya pada pernyataan impor:

• Sebelumnya (Implementasi Java 8 lama):

  // 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;
      }
  }

• Setelah (penerapan yang kompatibel dengan 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;
      }
  }

• Konfigurasi dependensi yang di-bundle (pom.xml): Untuk menyediakan class ini saat runtime, bundle library JAXB mandiri di dalam apiproxy/resources/java/ atau deklarasikan di 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>

Strategi 3A: Periode nonaktif untuk pemeliharaan terencana (Penerapan ulang di tempat)

Kapan harus digunakan: Direkomendasikan untuk lingkungan dengan masa pemeliharaan operasional terjadwal yang dapat menoleransi gangguan layanan singkat.

Prosedur:

1. Mengoordinasikan masa pemeliharaan terjadwal dengan konsumen API.
2. Upgrade komponen Edge for Private Cloud Anda ke versi 4.54.00 dengan mengikuti Panduan jalur upgrade.
3. Deploy revisi proxy API yang telah dikompilasi sebelumnya dan kompatibel dengan versi 4.54.00 menggunakan UI Edge Baru atau Apigee Management API (Deployments).
4. Verifikasi eksekusi info dengan mengirimkan permintaan pengujian sintetis ke Message Processor dan periksa log menggunakan alat Trace.
5. Tutup masa pemeliharaan dan buka kembali traffic publik.

Strategi 3B: Membuat lingkungan baru (Migrasi tanpa periode nonaktif)

Kapan harus digunakan: Direkomendasikan untuk lingkungan produksi penting yang memerlukan nol waktu henti. Gunakan ini jika Pemanggilan Java Anda tidak dapat diupdate agar berfungsi di Java 8 dan Java 21 secara bersamaan.

Cara kerjanya: Strategi ini melibatkan pengadaan satu atau beberapa lingkungan baru sehingga Anda dapat menghubungkan node Message Processor dari berbagai versi ke lingkungan tersebut. Selanjutnya, deploy proxy yang kompatibel dengan Java 8 ke lingkungan yang terhubung dengan Message Processor 4.53.X dan proxy yang kompatibel dengan Java 21 ke lingkungan yang terhubung dengan Message Processor 4.54.00. Kemudian, gunakan load balancer atau teknik perutean lainnya untuk merutekan traffic hanya ke proxy yang kompatibel dengan Java 21.

Untuk strategi ini, memahami cara organisasi, lingkungan, dan Message Processor berinteraksi adalah kunci untuk melakukan migrasi sistem tanpa waktu non-operasional (untuk mengetahui informasi selengkapnya, lihat Struktur organisasi Apigee Edge):

• Organisasi Apigee adalah batas administratif tingkat teratas yang berisi beberapa lingkungan (misalnya, prod, test).
• Revisi proxy API di-deploy ke lingkungan tertentu. Hanya Message Processor yang secara eksplisit terikat ke lingkungan tersebut yang memuat dan menjalankan revisi 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        |
          +------------------------------------------------------+

Prosedur:

1. Buat lingkungan sementara: Buat lingkungan baru (misalnya, prod-migration) dalam organisasi Anda (mengikuti Menyiapkan host dan lingkungan virtual) dengan host dan port virtual khusus.
2. Sediakan node Message Processor 4.54.00: Instal Edge for Private Cloud 4.54.00 di instance VM baru atau sementara, lalu ikat node ini ke prod-migration (lihat Menambahkan Message Processor).
3. Identifikasi proxy yang terpengaruh dan buat revisi yang diperbarui: Identifikasi proxy API menggunakan Pemanggilan Java (menggunakan alat deteksi perubahan) dan buat revisi baru dari setiap proxy yang terpengaruh dengan Pemanggilan Java yang kompatibel dengan Edge for Private Cloud 4.54.00 (menerapkan Strategi 1 atau Strategi 2).
4. Men-deploy revisi proxy yang dimodernisasi ke lingkungan sementara: Deploy revisi proxy yang kompatibel dan telah diupdate secara eksklusif ke prod-migration.
5. Verifikasi dan alihkan traffic: Jalankan pengujian verifikasi sintetis terhadap host virtual baru. Setelah diverifikasi, konfigurasi load balancer eksternal (F5, NGINX) untuk mengalihkan traffic klien dari prod ke prod-migration.
6. Mengupgrade node asli dan beralih kembali: Batalkan deployment proxy lama dari prod. Upgrade node Message Processor asli ke 4.54.00 dengan mengikuti Panduan jalur upgrade. Deploy revisi proxy yang dimodernisasi ke prod, alihkan kembali traffic load balancer ke prod, dan verifikasi operasi.
7. Menonaktifkan lingkungan sementara: Batalkan deployment proxy dari prod-migration, hapus node Message Processor sementara, dan hapus lingkungan sementara.

Strategi 3C: Penempatan lib eksternal tingkat node (Library fallback bersama)

Waktu penggunaan: Direkomendasikan jika Anda memiliki beberapa proxy API yang mengandalkan class Java yang dihapus di Java 21, dan mengompilasi ulang atau mengemas ulang setiap paket proxy secara individual sebelum upgrade tidak dapat dilakukan secara operasional.

Cara kerjanya: Di Edge untuk Private Cloud 4.54.00, Message Processor menyediakan mekanisme untuk memuat class Java yang tidak ada dari direktori node khusus: $APIGEE_ROOT/data/edge-message-processor/external-lib.

Jika mekanisme ini diaktifkan, Pemroses Pesan akan memeriksa direktori ini untuk menemukan class yang hilang sebelum kembali ke resolusi default. Anda dapat menyediakan class yang tidak ada dengan mengambilnya dari JAR library pihak ketiga atau dengan memaketkan class yang diperlukan ke dalam JAR dan menempatkannya di external-lib.

Prosedur:

1. Buat direktori library eksternal di setiap node Message Processor:

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

2. Tempatkan JAR yang diperlukan di direktori: Salin file JAR yang berisi class yang diperlukan ke /opt/apigee/data/edge-message-processor/external-lib.
3. Tetapkan izin file yang sesuai: Pastikan pengguna layanan apigee memiliki izin baca:

   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. Aktifkan pemuatan paket eksternal dalam konfigurasi Message Processor: Secara default di Edge untuk Private Cloud 4.54.00, pemuatan paket eksternal yang diizinkan dinonaktifkan (conf_system_java.21.enable.external.allowed.packages=false). Agar Message Processor dapat menyelesaikan dan memuat class dari /opt/apigee/data/edge-message-processor/external-lib, Anda harus mengaktifkan properti ini di /opt/apigee/customer/application/message-processor.properties menggunakan code with config (CwC):

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

5. Mulai ulang Pemroses Pesan:

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

Strategi 4: Flag JVM (--add-opens / --add-exports — perhatian dan upaya terakhir)

Waktu penggunaan: Gunakan strategi ini sebagai upaya terakhir untuk library vendor pihak ketiga tertutup yang kode sumbernya tidak tersedia, vendor belum merilis update Java 21, dan JAR sangat bergantung pada akses reflektif ke paket Java internal.

Prosedur:

1. Identifikasi paket yang tidak dapat diakses yang digunakan untuk refleksi: Tentukan modul dan paket Java internal yang diakses secara reflektif oleh library pihak ketiga Anda. Catatan: Error refleksi ini hanya terjadi di Java 21 di Edge for Private Cloud 4.54.00 dan tidak akan muncul di log versi 4.53.x. Periksa log Message Processor (/opt/apigee/var/log/edge-message-processor/system.log) pasca-upgrade untuk menemukan InaccessibleObjectException yang mengidentifikasi modul dan paket yang diperlukan:

   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. Edit /opt/apigee/customer/application/message-processor.properties menggunakan code with config (CwC) (buat file jika belum ada).
3. Tambahkan flag --add-opens atau --add-exports yang ditargetkan ke 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. Pastikan kepemilikan dan izin file yang tepat:

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

5. Mulai ulang Message Processor menggunakan apigee-service:

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

Perubahan TLS dan cipher suite

Di Edge untuk Private Cloud 4.54.00, komponen platform inti—termasuk Message Processor, Management Server, dan Router—diupdate untuk berjalan di Java 21 LTS. Update ini memodernisasi keamanan kriptografis dengan mengaktifkan TLS 1.3 secara default (JEP 332). Prosesor Pesan kini menegosiasikan TLS 1.3 sebagai protokol pilihan untuk koneksi backend keluar, dan melakukan penggantian ke TLS 1.2 jika backend tidak mendukungnya.

Persyaratan dan perbaikan backend lama

Baseline kriptografis Java 21 memperbarui daftar protokol dan cipher suite yang dinonaktifkan secara default di jdk.tls.disabledAlgorithms (seperti protokol TLS lama dan suite pertukaran kunci RSA statis non-forward-secret: TLS_RSA_*). Karena Anda menyediakan runtime Java 21 Anda sendiri, daftar persis protokol dan cipher suite yang dinonaktifkan bergantung pada implementasi Java 21 spesifik Anda.

Jika proxy API yang ada terhubung ke infrastruktur backend lama yang memerlukan protokol yang dinonaktifkan atau cipher RSA statis, tinjau tindakan berikut:

• Modernisasi keamanan backend (Direkomendasikan): Upgrade server target dan load balancer untuk mendukung TLS 1.2 atau TLS 1.3 dengan cipher suite ECDHE modern. Untuk mengonfigurasi protokol dan cipher suite di proxy API, lihat Mengonfigurasi TLS dari Edge ke backend dan referensi konfigurasi TargetEndpoint TLS/SSL (atau Load balancing di seluruh server backend jika menggunakan TargetServer).
• Mengaktifkan kembali algoritma lama menggunakan CwC (tindakan transisi selama upgrade): Jika upgrade backend tidak dapat diselesaikan sebelum upgrade platform, Anda dapat mengaktifkan kembali algoritma yang diperlukan untuk sementara menggunakan code with config (CwC):
  1. Periksa nilai jdk.tls.disabledAlgorithms default di penginstalan Java 21 Anda (misalnya, di $JAVA_HOME/conf/security/java.security).
  2. Ganti conf_jvmsecurity_jdk.tls.disabledAlgorithms di /opt/apigee/customer/application/message-processor.properties dengan daftar algoritma yang dinonaktifkan yang sama, dengan hanya menghapus entri TLS_RSA_* (biarkan semua algoritma lain yang dinonaktifkan tetap utuh sehingga perlindungan yang tersisa tetap diaktifkan).
  3. Mulai ulang Message Processor menggunakan apigee-service. Hapus penggantian ini setelah backend mendukung cipher suite ECDHE.
• Memperbarui daftar yang diizinkan untuk cipher suite kustom: Jika Anda sebelumnya telah mengganti conf_http_HTTPTransport.ssl.cipher.suites.whitelist, tinjau sebelum melakukan upgrade. Java 21 tidak lagi mendukung suite RSA statis (TLS_RSA_*), sehingga daftar yang diizinkan yang hanya berisi suite tersebut membuat Message Processor tidak memiliki cipher yang dapat digunakan dan panggilan backend gagal dengan no cipher suites in common. Hapus entri TLS_RSA_* dan konfigurasi cipher suite modern yang didukung oleh implementasi Java 21 Anda. Jika Anda belum mengganti properti ini, default 4.54.00 sudah membawa suite yang didukung dan tidak diperlukan perubahan.
• Perbarui sandi Router internal ke Message Processor: Jika sebelumnya Anda telah mengganti conf_message-processor-communication_local.http.ssl.ciphers dengan rangkaian RSA statis, perbarui dengan rangkaian sandi modern yang didukung oleh penerapan Java 21 Anda sebelum melakukan upgrade, atau Router tidak dapat menyelesaikan TLS handshake dengan Message Processor. Kemudian, mulai ulang Message Processor:

  apigee-service edge-message-processor restart

  Lihat Mengonfigurasi TLS antara Router dan Message Processor.

Untuk mengetahui detail tentang cara mengonfigurasi TLS di antara komponen Edge, lihat Mengonfigurasi TLS antara Router dan Message Processor.

Alat deteksi perubahan

Apigee menyediakan alat deteksi perubahan untuk memindai cluster Anda guna menemukan proxy API, kebijakan, alur bersama, dan JAR resource yang di-deploy yang mungkin terpengaruh oleh upgrade ke Edge for Private Cloud 4.54.00.

Alat ini mengidentifikasi potensi pemblokir upgrade—termasuk library yang tidak kompatibel dengan Java 21, API internal yang dienkapsulasi dengan kuat, penghentian kebijakan lama, dan batas RDN OpenLDAP—serta menghasilkan laporan yang dapat ditindaklanjuti untuk membantu Anda memilih strategi perbaikan yang sesuai.

Untuk mengetahui prasyarat lengkap, petunjuk download, sintaksis command line, dan contoh laporan, lihat Panduan alat deteksi perubahan khusus.