Thay đổi trong Edge cho đám mây riêng tư 4.54.00

Tổng quan về những thay đổi

Edge for Private Cloud 4.54.00 giới thiệu nhiều thay đổi giúp tăng cường trạng thái bảo mật của nền tảng và cập nhật các thành phần của nền tảng để chạy bằng Java 21. Hai phần dưới đây đề cập đến những thay đổi này:

• Thay đổi đối với chính sách Chú thích Java
• Thay đổi về TLS và bộ thuật toán mật mã

Ngoài những thay đổi này, hãy xem hướng dẫn riêng về công cụ phát hiện thay đổi. Tiện ích này được cung cấp để xác định những thay đổi đối với các proxy, luồng dùng chung hoặc các cấu phần phần mềm khác trong cụm có thể gây ra sự gián đoạn do quá trình nâng cấp này.

Thay đổi đối với chính sách Chú thích Java

Trong Edge cho đám mây riêng tư phiên bản 4.54.00, các thành phần nền tảng cốt lõi (bao gồm Bộ xử lý thông báo, Máy chủ quản lý và Bộ định tuyến) được cập nhật để chạy trên Java 21 LTS. Java 21 hiện đại hoá Nền tảng Java, bao gồm cả việc xoá các mô-đun Java EE và CORBA cũ (JEP 320), xoá các lớp tiện ích nội bộ cũ và thực thi tính năng đóng gói mô-đun mạnh mẽ (JEP 403).

Do những thay đổi này, các proxy API có chính sách JavaCallout tuỳ chỉnh hoặc JAR tài nguyên tuỳ chỉnh (được lưu trữ ở cấp proxy, môi trường hoặc tổ chức) có thể bị gián đoạn khi nâng cấp lên phiên bản 4.54.00.

Các danh mục thay đổi có thể ảnh hưởng đến Chú thích Java

1. Xoá vĩnh viễn các mô-đun Java EE và CORBA (JEP 320): Các mô-đun được tích hợp sẵn vào thời gian chạy Java 8 (bao gồm JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.* và CORBA org.omg.*) đã bị xoá khỏi Java SE. Các chú thích tham chiếu đến những gói này mà không có gói thay thế độc lập sẽ không hoạt động trong thời gian chạy và trả về lỗi NoClassDefFoundError.
2. Đã xoá các lớp tiện ích nội bộ: Đã xoá các trình trợ giúp nội bộ cũ như sun.misc.BASE64Encoder và sun.misc.BASE64Decoder. Các chú thích gọi những lớp này sẽ không thành công và báo lỗi NoClassDefFoundError.
3. Đóng gói mạnh mẽ các thành phần nội bộ của Java (JEP 403): Không thể truy cập vào các gói nội bộ trong java.base (chẳng hạn như sun.security.*, sun.reflect.* và com.sun.*) bằng cách phản chiếu từ chú thích tuỳ chỉnh. Các lệnh gọi phản chiếu không thành công trong thời gian chạy với InaccessibleObjectException.
4. Các thay đổi và việc xoá chữ ký phương thức trong các lớp Java còn tồn tại: Trong một số mô-đun Java, lớp vẫn có trong Java 21, nhưng các hàm khởi tạo hoặc chữ ký phương thức cụ thể đã bị xoá, không dùng nữa hoặc thay đổi (chẳng hạn như các phương thức phân tích cú pháp DOM cụ thể trong org.w3c.dom.Document và các lớp phân tích cú pháp XML có liên quan).

   Phát hiện công cụ: Công cụ phát hiện thay đổi sẽ gắn cờ các tệp đối chiếu đến những lớp này trong danh mục METHOD_SIGNATURE_MODIFICATION có MEDIUMMức độ chắc chắn về tác động, nhắc nhà phát triển kiểm tra mã nguồn của chú thích để tìm các lệnh gọi phương thức đã sửa đổi.

Chiến lược khắc phục

Trước khi nâng cấp, hãy đảm bảo rằng các chính sách về Lời gọi Java và tài nguyên JAR tuỳ chỉnh của bạn tương thích với thời gian chạy Java 21. Việc sử dụng công cụ phát hiện thay đổi sẽ giúp bạn xác định các proxy API, luồng dùng chung và tài nguyên JAR của môi trường hoặc tổ chức bị ảnh hưởng trên cụm của bạn.

Các chiến lược khắc phục được mô tả trong phần này là hướng dẫn chung và không loại trừ lẫn nhau. Tuỳ thuộc vào yêu cầu hoạt động, bạn có thể kết hợp các chiến lược, chẳng hạn như hiện đại hoá mã nguồn chú thích bằng Chiến lược 2 và triển khai các bản sửa đổi proxy đã cập nhật bằng Chiến lược 3B để không bị gián đoạn trong quá trình nâng cấp Bộ xử lý thông báo.

Chiến lược 3A, 3B và 3C là 3 cách thực hiện cùng một phương pháp vận hành: nâng cấp nút và triển khai lại proxy vào những thời điểm khác nhau mà không thay đổi gói proxy. Chọn một hoặc kết hợp các lựa chọn này dựa trên yêu cầu về tính sẵn có của API.

Hãy xem hướng dẫn quyết định sau đây để chọn phương pháp phù hợp nhất cho việc triển khai của bạn:

Hướng dẫn đưa ra quyết định về các biện pháp giảm thiểu liên quan đến Java Callout:

Chiến lược 1: Proxy tương thích kép thông qua các JAR đi kèm (Kiểm thử trước khi nâng cấp để không bị thời gian ngừng hoạt động)

Trường hợp sử dụng: Sử dụng chiến lược này khi:

• Có một thư viện thay thế độc lập tương thích kép: Có một JAR thay thế triển khai chức năng bắt buộc và có thể được gói trực tiếp vào proxy API của bạn mà không cần sửa đổi mã nguồn.
• Bạn muốn các proxy API và chú thích Java hiện có hoạt động liền mạch trên cả phiên bản hiện tại (ví dụ: Edge cho đám mây riêng tư 4.53.01) và phiên bản đã nâng cấp (Edge cho đám mây riêng tư 4.54.00).
• Bạn muốn kiểm thử và xác minh tất cả thay đổi trong môi trường thử nghiệm và môi trường thực tế trước khi nâng cấp cụm Edge for Private Cloud, đảm bảo không có vấn đề ngoài dự kiến và không có thời gian ngừng hoạt động trong lưu lượng truy cập thực tế.
• Bạn muốn tránh viết lại hoặc tái cấu trúc logic nghiệp vụ Lời gọi Java.

Cách hoạt động: Trong Java 8, một số thư viện nhất định (chẳng hạn như JAXB javax.xml.bind.* hoặc Activation javax.activation.*) được tích hợp trực tiếp vào thời gian chạy Java 8. Do đó, nhà phát triển không cần đưa thêm tệp JAR vào gói proxy của họ. Trong Java 21, các thư viện này đã bị xoá khỏi thời gian chạy Java.

Cách làm cho proxy của bạn "tương thích kép" trên Edge cho Private Cloud 4.53.x và 4.54.00:

1. Xác định thư viện bị thiếu mà chú thích của bạn yêu cầu (ví dụ: JAXB hoặc Activation).
2. Tải JAR thay thế nguồn mở độc lập (ví dụ: jakarta.xml.bind-api-2.3.3.jar và jaxb-runtime-2.3.8.jar).
3. Hãy đặt tệp JAR thay thế trực tiếp vào gói proxy trong apiproxy/resources/java/ hoặc tải tệp đó lên bản sửa đổi proxy bằng API tệp tài nguyên cấp proxy hoặc tải tệp đó lên dưới dạng tệp tài nguyên ở cấp môi trường hoặc cấp tổ chức. Để biết thêm thông tin về cách quản lý tệp tài nguyên, hãy xem Tài liệu về tệp tài nguyên của Apigee.
4. Triển khai và kiểm thử trước khi nâng cấp: Message Processor trong cả Edge for Private Cloud 4.53.x và 4.54.00 đều tải các lớp từ những JAR đi kèm này. Giờ đây, bạn có thể triển khai gói proxy đã cập nhật này và kiểm thử bằng lưu lượng truy cập giả tạo trong cụm Edge cho Đám mây riêng 4.53.x hiện tại.
5. Bật tính năng tải gói bên ngoài được cho phép trên Bộ xử lý thông báo (Bắt buộc đối với phiên bản 4.54.00): Theo mặc định trong Edge cho đám mây riêng tư phiên bản 4.54.00, tính năng tải các gói Java đã xoá (chẳng hạn như javax.xml.bind.* và javax.activation.*) từ các tệp JAR tài nguyên bên ngoài hoặc đi kèm sẽ bị tắt (conf_system_java.21.enable.external.allowed.packages=false), vì vậy, việc chỉ đóng gói các tệp JAR sẽ không hoạt động theo mặc định. Bạn phải bật thuộc tính này trong /opt/apigee/customer/application/message-processor.properties bằng cách sử dụng mã có cấu hình (CwC) (bạn có thể định cấu hình thuộc tính này trước khi nâng cấp nút Bộ xử lý thông báo hoặc đặt thuộc tính này sau khi nâng cấp và khởi động lại Bộ xử lý thông báo):

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

6. Không có vấn đề về lưu lượng truy cập trực tiếp sau khi nâng cấp: Khi cụm của bạn được nâng cấp lên Edge cho đám mây riêng tư 4.54.00 và bật conf_system_java.21.enable.external.allowed.packages=true, Trình xử lý thông báo đã có sẵn tệp JAR cần thiết và tải các lớp từ tệp tài nguyên đi kèm mà không gặp lỗi (NoClassDefFoundError), đảm bảo quá trình nâng cấp diễn ra suôn sẻ và không có thời gian ngừng hoạt động.

Ví dụ về mã: Chú thích phân tích cú pháp và xác thực XML của đơn đặt hàng

Hãy cân nhắc một Apigee Java Callout điển hình, trích xuất và xác thực các đơn đặt hàng XML đến bằng JAXB (JAXBContext và Unmarshaller).

• Trước khi khắc phục (Không thành công trong Edge for Private Cloud 4.54.00): Trong Edge for Private Cloud 4.53.x, gói proxy chỉ chứa tệp JAR chú thích, dựa vào thư viện thời gian chạy Java 8 tích hợp sẵn cho JAXB:

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

  Cách triển khai chú thích 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) { }
      }
  }

  Lỗi: Trong Edge cho đám mây riêng tư 4.53.x, thao tác này sẽ thực thi mà không gặp vấn đề gì. Sau khi nút được nâng cấp lên Edge cho đám mây riêng tư 4.54.00, proxy này sẽ không hoạt động ngay lập tức trong quá trình xử lý yêu cầu:

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

• Sau khi khắc phục (Tương thích kép trên Edge cho Private Cloud 4.53.x và 4.54.00): Bạn không cần phải viết lại hoặc biên dịch lại mã Java Callout. Bạn có thể trực tiếp làm cho proxy của mình tương thích kép bằng cách cung cấp các tệp JAR độc lập:
  1. Gói hoặc tải trực tiếp các tệp JAR độc lập lên: Lấy các thư viện JAXB độc lập (jakarta.xml.bind-api-2.3.3.jar và jaxb-runtime-2.3.8.jar) rồi đặt các thư viện đó vào trong gói proxy của bạn trong apiproxy/resources/java/:

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

     Ngoài ra, hãy tải jakarta.xml.bind-api-2.3.3.jar và jaxb-runtime-2.3.8.jar lên dưới dạng tệp tài nguyên bằng Resource Files API cấp proxy hoặc ở cấp môi trường hoặc cấp tổ chức để tất cả proxy trong cùng một phạm vi có thể chia sẻ các tệp đó mà không cần gói chúng vào từng gói proxy riêng lẻ.

     Nếu bạn tạo gói proxy từ nguồn bằng Maven, hãy khai báo các phần phụ thuộc này trong pom.xml để chúng được đóng gói tự động trong quá trình tạo bản dựng.

  2. Triển khai và kiểm thử trên cụm 4.53.x hiện tại: Triển khai gói proxy đã cập nhật cho môi trường Edge for Private Cloud 4.53.x hiện tại và gửi lệnh gọi kiểm thử. Vì Bộ xử lý thông báo Edge for Private Cloud 4.53.x tải các lớp từ những JAR đi kèm này, nên bạn có thể xác minh rằng lệnh gọi tiếp tục hoạt động giống hệt nhau.
  3. Bật tính năng tải gói được phép bên ngoài thông qua CwC: Vì tính năng tải gói được phép bên ngoài bị tắt theo mặc định trong Edge cho đám mây riêng tư 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false), hãy bật tính năng này trên mỗi nút Bộ xử lý thông báo trong /opt/apigee/customer/application/message-processor.properties bằng cách sử dụng mã có cấu hình (CwC):

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

  4. Không gặp vấn đề nào về lưu lượng truy cập trực tiếp sau khi nâng cấp: Sau khi được xác thực trong môi trường 4.53.x và được định cấu hình bằng thuộc tính CwC, proxy của bạn sẽ được chuẩn bị đầy đủ. Khi bạn nâng cấp cụm lên Edge cho đám mây riêng tư 4.54.00, Bộ xử lý thông báo sẽ tải các lớp JAXB đi kèm, đảm bảo không có lỗi và không làm gián đoạn lưu lượng truy cập trực tiếp.

Chiến lược 2: Triển khai thay thế (Hiện đại hoá mã và phần phụ thuộc)

Trường hợp nên sử dụng: Nên dùng cho các cơ sở mã đang hoạt động mà mã nguồn proxy được duy trì dễ dàng. Đây là phương pháp rõ ràng nhất về lâu dài để tuân thủ Java 21. Lưu ý về việc triển khai: Vì việc triển khai các bản sửa đổi proxy hiện đại hoá đòi hỏi sự phối hợp của Trình xử lý thông báo, hãy kết hợp chiến lược này với Chiến lược 3A (trong thời gian bảo trì theo kế hoạch) hoặc Chiến lược 3B (để đạt được thời gian ngừng hoạt động bằng 0 với Trình xử lý thông báo song song).

Cách hoạt động: Thay thế các lớp nội bộ Java đã bị xoá bằng API Java SE tiêu chuẩn chính thức hoặc các lớp tương đương độc lập nguồn mở, đồng thời đóng gói các phần phụ thuộc bắt buộc của bên thứ ba ngay trong tệp tài nguyên hoặc POM của gói proxy.

Ví dụ về mã:

Ví dụ 1: Hiện đại hoá phương thức và mã (Thay thế các tiện ích nội bộ đã bị xoá)

Trong Java 8, chú thích thường dùng các lớp tiện ích nội bộ như sun.misc.BASE64Encoder. Trong Java hiện đại, các lớp này đã bị xoá, nhưng API java.util.Base64 tiêu chuẩn cung cấp các lớp thay thế trực tiếp mà không cần tệp JAR phần phụ thuộc bên ngoài:

• Trước (Triển khai Java 8 cũ):

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

• Sau (triển khai tuân thủ 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;
      }
  }

Ví dụ 2: Tái cấu trúc ở cấp độ nhập bằng thư viện đi kèm (JAXB Namespace Prefix Mapper)

Trong Java 8, các proxy API tuỳ chỉnh tiền tố không gian tên XML thường mở rộng trình ánh xạ JAXB nội bộ của Sun com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. Trong Java 21, các gói Sun nội bộ sẽ bị xoá và không thể truy cập được.

Thư viện nguồn mở độc lập (org.glassfish.jaxb:jaxb-runtime) cung cấp lớp giống hệt trong com.sun.xml.bind.marshaller.NamespacePrefixMapper. Tất cả chữ ký, tham số và kiểu dữ liệu trả về của phương thức đều giống hệt nhau – thay đổi về mã chỉ nằm ở câu lệnh nhập:

• Trước (Triển khai Java 8 cũ):

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

• Sau (triển khai tuân thủ 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;
      }
  }

• Cấu hình phần phụ thuộc đi kèm (pom.xml): Để cung cấp lớp này trong thời gian chạy, hãy gói các thư viện JAXB độc lập bên trong apiproxy/resources/java/ hoặc khai báo các thư viện đó trong 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>

Chiến lược 3A: Thời gian ngừng hoạt động để bảo trì theo kế hoạch (Triển khai lại tại chỗ)

Trường hợp sử dụng: Nên dùng cho những môi trường có khoảng thời gian bảo trì hoạt động theo lịch và có thể chấp nhận tình trạng gián đoạn dịch vụ trong thời gian ngắn.

Quy trình:

1. Phối hợp với người dùng API để lên lịch thời gian bảo trì.
2. Nâng cấp các thành phần Edge cho đám mây riêng tư lên phiên bản 4.54.00 theo Hướng dẫn về lộ trình nâng cấp.
3. Triển khai bản sửa đổi đã biên dịch trước, tương thích với phiên bản 4.54.00 của proxy API bằng Giao diện người dùng Edge mới hoặc API Quản lý Apigee (Triển khai).
4. Xác minh việc thực thi chú thích bằng cách gửi các yêu cầu kiểm thử giả tạo đến Trình xử lý thông báo và kiểm tra nhật ký bằng Công cụ theo dõi.
5. Đóng thời gian bảo trì và mở lại lưu lượng truy cập công khai.

Chiến lược 3B: Tạo môi trường mới (Di chuyển mà không bị gián đoạn)

Trường hợp sử dụng: Nên dùng cho các môi trường thực tế quan trọng, không được phép có thời gian ngừng hoạt động. Hãy sử dụng cách này khi bạn không thể cập nhật Java Callout để hoạt động đồng thời trên Java 8 và Java 21.

Cách hoạt động: Chiến lược này liên quan đến việc mua một hoặc nhiều môi trường mới để bạn có thể kết nối các nút Message Processor của nhiều phiên bản với môi trường đó. Sau đó, triển khai các proxy tương thích với Java 8 cho môi trường được kết nối với Bộ xử lý thông báo 4.53.X và các proxy tương thích với Java 21 cho môi trường được kết nối với Bộ xử lý thông báo 4.54.00. Sau đó, hãy sử dụng trình cân bằng tải hoặc các kỹ thuật định tuyến khác để chỉ định tuyến lưu lượng truy cập đến proxy tương thích với Java 21.

Đối với chiến lược này, việc hiểu rõ cách các tổ chức, môi trường và Bộ xử lý thông báo tương tác là yếu tố then chốt để chuyển đổi mà không gây ra thời gian ngừng hoạt động (để biết thêm thông tin, hãy xem phần Cấu trúc tổ chức của Apigee Edge):

• Tổ chức Apigee là ranh giới quản trị cấp cao nhất chứa nhiều môi trường (ví dụ: prod, test).
• Một bản sửa đổi proxy API được triển khai cho một môi trường cụ thể. Chỉ những Trình xử lý thông báo được liên kết rõ ràng với môi trường đó mới tải và thực thi bản sửa đổi 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        |
          +------------------------------------------------------+

Quy trình:

1. Tạo môi trường tạm thời: Tạo một môi trường mới (ví dụ: prod-migration) trong tổ chức của bạn (theo Thiết lập máy chủ và môi trường ảo) bằng một máy chủ và cổng ảo chuyên dụng.
2. Cung cấp các nút Trình xử lý thông báo 4.54.00: Cài đặt Edge cho Đám mây riêng tư 4.54.00 trên các phiên bản VM mới hoặc tạm thời và liên kết các nút này với prod-migration (xem phần Thêm Trình xử lý thông báo).
3. Xác định các proxy bị ảnh hưởng và tạo bản sửa đổi mới: Xác định các proxy API sử dụng Java Callout (bằng công cụ phát hiện thay đổi) và tạo một bản sửa đổi mới cho mỗi proxy bị ảnh hưởng bằng Java Callout tương thích với Edge for Private Cloud 4.54.00 (áp dụng Chiến lược 1 hoặc Chiến lược 2).
4. Triển khai các bản sửa đổi proxy hiện đại hoá cho môi trường tạm thời: Triển khai các bản sửa đổi proxy tương thích và đã cập nhật riêng cho prod-migration.
5. Xác minh và chuyển lưu lượng truy cập: Thực hiện các bài kiểm thử xác minh tổng hợp đối với máy chủ ảo mới. Sau khi xác minh, hãy định cấu hình bộ cân bằng tải bên ngoài (F5, NGINX) để chuyển hướng lưu lượng truy cập của ứng dụng khách từ prod sang prod-migration.
6. Nâng cấp các nút ban đầu và chuyển về: Huỷ triển các proxy cũ khỏi prod. Nâng cấp các nút Bộ xử lý thông báo ban đầu lên phiên bản 4.54.00 theo Hướng dẫn về lộ trình nâng cấp. Triển khai các bản sửa đổi proxy hiện đại hoá cho prod, chuyển hướng lưu lượng truy cập của trình cân bằng tải trở lại prod và xác minh hoạt động.
7. Ngừng hoạt động môi trường tạm thời: Huỷ triển khai proxy khỏi prod-migration, xoá các nút Bộ xử lý thông báo tạm thời và xoá môi trường tạm thời.

Chiến lược 3C: Vị trí thư viện bên ngoài ở cấp nút (Thư viện dự phòng dùng chung)

Trường hợp nên sử dụng: Bạn nên sử dụng khi có nhiều proxy API dựa vào các lớp Java đã bị xoá trong Java 21 và việc biên dịch lại hoặc đóng gói lại từng gói proxy riêng lẻ trước khi nâng cấp là không khả thi về mặt vận hành.

Cách hoạt động: Trong Edge cho đám mây riêng tư 4.54.00, Bộ xử lý thông báo cung cấp một cơ chế để tải các lớp Java bị thiếu từ một thư mục nút chuyên dụng: $APIGEE_ROOT/data/edge-message-processor/external-lib.

Khi cơ chế này được bật, Trình xử lý thông báo sẽ kiểm tra thư mục này để tìm các lớp bị thiếu trước khi quay lại độ phân giải mặc định. Bạn có thể cung cấp các lớp bị thiếu bằng cách lấy chúng từ các tệp JAR thư viện của bên thứ ba hoặc bằng cách gói các lớp bắt buộc vào một tệp JAR rồi đặt tệp đó vào external-lib.

Quy trình:

1. Tạo thư mục thư viện bên ngoài trên mỗi nút Message Processor:

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

2. Đặt các tệp JAR bắt buộc vào thư mục: Sao chép các tệp JAR chứa các lớp bắt buộc vào /opt/apigee/data/edge-message-processor/external-lib.
3. Đặt quyền truy cập tệp phù hợp: Đảm bảo người dùng dịch vụ apigee có quyền đọc:

   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. Bật tính năng tải gói bên ngoài trong cấu hình Trình xử lý thông báo: Theo mặc định trong Edge cho đám mây riêng tư 4.54.00, tính năng tải các gói được phép bên ngoài sẽ bị tắt (conf_system_java.21.enable.external.allowed.packages=false). Để cho phép Trình xử lý thông báo phân giải và tải các lớp từ /opt/apigee/data/edge-message-processor/external-lib, bạn phải bật thuộc tính này trong /opt/apigee/customer/application/message-processor.properties bằng cách sử dụng mã có cấu hình (CwC):

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

5. Khởi động lại Bộ xử lý thông báo:

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

Chiến lược 4: Cờ JVM (--add-opens / --add-exports — thận trọng và là phương án cuối cùng)

Thời điểm sử dụng: Sử dụng chiến lược này như phương án cuối cùng cho các thư viện nguồn đóng của nhà cung cấp bên thứ ba khi không có mã nguồn, nhà cung cấp chưa phát hành bản cập nhật Java 21 và JAR hoàn toàn phụ thuộc vào quyền truy cập phản chiếu vào các gói Java nội bộ.

Quy trình:

1. Xác định gói không thể truy cập được dùng để phản chiếu: Xác định mô-đun và gói Java nội bộ mà thư viện bên thứ ba truy cập theo cách phản chiếu. Lưu ý: Những lỗi phản chiếu này chỉ xảy ra trong Java 21 trong Edge cho Private Cloud 4.54.00 và sẽ không xuất hiện trong nhật ký phiên bản 4.53.x. Kiểm tra nhật ký Message Processor (/opt/apigee/var/log/edge-message-processor/system.log) sau khi nâng cấp để tìm InaccessibleObjectException xác định mô-đun và gói bắt buộc:

   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. Chỉnh sửa /opt/apigee/customer/application/message-processor.properties bằng code with config (CwC) (tạo tệp nếu chưa có).
3. Thêm cờ --add-opens hoặc --add-exports được nhắm mục tiêu vào 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. Đảm bảo quyền sở hữu và quyền đối với tệp phù hợp:

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

5. Khởi động lại Bộ xử lý thông báo bằng apigee-service:

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

Những thay đổi về TLS và bộ thuật toán mật mã

Trong Edge cho đám mây riêng tư phiên bản 4.54.00, các thành phần nền tảng cốt lõi (bao gồm Bộ xử lý thông báo, Máy chủ quản lý và Bộ định tuyến) được cập nhật để chạy trên Java 21 LTS. Bản cập nhật này hiện đại hoá tính bảo mật bằng mật mã bằng cách bật TLS 1.3 theo mặc định (JEP 332). Giờ đây, Bộ xử lý thông báo sẽ thương lượng TLS 1.3 làm giao thức ưu tiên cho các kết nối phụ trợ gửi đi, quay lại TLS 1.2 khi phần phụ trợ không hỗ trợ giao thức này.

Yêu cầu và biện pháp khắc phục đối với phần phụ trợ cũ

Đường cơ sở mật mã Java 21 cập nhật danh sách các giao thức và bộ thuật toán mật mã bị vô hiệu hoá theo mặc định trong jdk.tls.disabledAlgorithms (chẳng hạn như các giao thức TLS cũ và các bộ trao đổi khoá RSA tĩnh không có tính bảo mật chuyển tiếp: TLS_RSA_*). Vì bạn cung cấp thời gian chạy Java 21 của riêng mình, nên danh sách chính xác các giao thức và bộ thuật toán mật mã bị vô hiệu hoá sẽ phụ thuộc vào việc triển khai Java 21 cụ thể của bạn.

Nếu các proxy API hiện có của bạn kết nối với cơ sở hạ tầng phụ trợ cũ yêu cầu các giao thức bị vô hiệu hoá hoặc mật mã RSA tĩnh, hãy xem xét các hành động sau:

• Hiện đại hoá tính bảo mật của phần phụ trợ (Nên dùng): Nâng cấp máy chủ mục tiêu và trình cân bằng tải để hỗ trợ TLS 1.2 hoặc TLS 1.3 bằng bộ thuật toán mật mã ECDHE hiện đại. Để định cấu hình giao thức và bộ thuật toán mật mã trong proxy API, hãy xem bài viết Định cấu hình TLS từ Edge đến phần phụ trợ và Tài liệu tham khảo về cấu hình TargetEndpoint TLS/SSL (hoặc Cân bằng tải trên các máy chủ phụ trợ nếu sử dụng TargetServers).
• Bật lại các thuật toán cũ bằng CwC (biện pháp chuyển tiếp trong quá trình nâng cấp): Nếu không thể hoàn tất việc nâng cấp phần phụ trợ trước khi nâng cấp nền tảng, bạn có thể tạm thời bật lại các thuật toán bắt buộc bằng mã có cấu hình (CwC):
  1. Kiểm tra giá trị jdk.tls.disabledAlgorithms mặc định trong bản cài đặt Java 21 (ví dụ: trong $JAVA_HOME/conf/security/java.security).
  2. Ghi đè conf_jvmsecurity_jdk.tls.disabledAlgorithms trong /opt/apigee/customer/application/message-processor.properties bằng cùng danh sách thuật toán bị vô hiệu hoá đó, chỉ xoá mục TLS_RSA_* (giữ nguyên tất cả các thuật toán bị vô hiệu hoá khác để các biện pháp bảo vệ còn lại vẫn được bật).
  3. Khởi động lại Trình xử lý thông báo bằng apigee-service. Xoá chế độ ghi đè này sau khi phần phụ trợ hỗ trợ bộ thuật toán mật mã ECDHE.
• Cập nhật danh sách cho phép bộ thuật toán mật mã tuỳ chỉnh: Nếu trước đây bạn đã ghi đè conf_http_HTTPTransport.ssl.cipher.suites.whitelist, hãy xem lại trước khi nâng cấp. Java 21 không còn hỗ trợ các bộ RSA tĩnh (TLS_RSA_*), vì vậy, danh sách cho phép chỉ chứa các bộ này sẽ khiến Trình xử lý thông báo không có thuật toán mật mã nào có thể sử dụng và các lệnh gọi phụ trợ sẽ gặp lỗi với no cipher suites in common. Xoá các mục TLS_RSA_* và định cấu hình các bộ thuật toán mật mã hiện đại mà chế độ triển khai Java 21 của bạn hỗ trợ. Nếu bạn chưa ghi đè thuộc tính này, thì các giá trị mặc định của phiên bản 4.54.00 đã có sẵn các bộ được hỗ trợ và bạn không cần thay đổi gì.
• Cập nhật mật mã nội bộ của Bộ định tuyến thành Bộ xử lý thông báo: Nếu trước đây bạn đã ghi đè conf_message-processor-communication_local.http.ssl.ciphers bằng các bộ RSA tĩnh, hãy cập nhật bộ này bằng các bộ thuật toán mật mã hiện đại được bản triển khai Java 21 hỗ trợ trước khi nâng cấp, nếu không, Bộ định tuyến sẽ không thể hoàn tất quá trình bắt tay TLS với Bộ xử lý thông báo. Sau đó, hãy khởi động lại Bộ xử lý thông báo:

  apigee-service edge-message-processor restart

  Xem phần Định cấu hình TLS giữa Bộ định tuyến và Bộ xử lý thông báo.

Để biết thông tin chi tiết về cách định cấu hình TLS giữa các thành phần Edge, hãy xem bài viết Định cấu hình TLS giữa Bộ định tuyến và Bộ xử lý thông báo.

Công cụ phát hiện thay đổi

Apigee cung cấp một công cụ phát hiện thay đổi để quét cụm của bạn nhằm tìm các proxy API, chính sách, luồng chia sẻ và JAR tài nguyên đã triển khai có thể bị ảnh hưởng bởi quá trình nâng cấp lên Edge cho Đám mây riêng tư 4.54.00.

Công cụ này xác định các yếu tố có thể cản trở quá trình nâng cấp, bao gồm các thư viện không tương thích với Java 21, các API nội bộ được đóng gói chặt chẽ, các chính sách cũ không còn được dùng nữa và các giới hạn RDN của OpenLDAP, đồng thời tạo ra các báo cáo hữu ích để giúp bạn chọn chiến lược khắc phục phù hợp.

Để biết đầy đủ các điều kiện tiên quyết, hướng dẫn tải xuống, cú pháp dòng lệnh và báo cáo mẫu, hãy xem Hướng dẫn về công cụ phát hiện thay đổi chuyên biệt.