프라이빗 클라우드용 Edge 4.54.00의 변경사항

변경사항 개요

프라이빗 클라우드용 Edge 4.54.00에서는 플랫폼의 보안 상황을 개선하는 여러 변경사항이 도입되고 Java 21로 실행되도록 플랫폼 구성요소가 업데이트됩니다. 아래의 두 섹션에서 이러한 변경사항을 설명합니다.

이러한 변경사항 외에도 전용 변경 감지 도구 가이드를 검토하세요. 이 유틸리티는 이번 업그레이드로 인해 중단을 일으킬 수 있는 클러스터의 프록시, 공유 흐름 또는 기타 아티팩트의 변경사항을 식별하는 데 사용할 수 있습니다.

Java 콜아웃 정책 변경사항

프라이빗 클라우드용 Edge 4.54.00에서는 메시지 프로세서, 관리 서버, 라우터를 비롯한 핵심 플랫폼 구성요소가 Java 21 LTS에서 실행되도록 업데이트되었습니다. Java 21은 Java 플랫폼을 현대화합니다. 여기에는 기존 Java EE 및 CORBA 모듈 삭제 (JEP 320), 기존 내부 유틸리티 클래스 삭제, 강력한 모듈식 캡슐화 적용 (JEP 403)이 포함됩니다.

이러한 변경사항으로 인해 맞춤 JavaCallout 정책 또는 맞춤 리소스 JAR (프록시, 환경 또는 조직 수준에 저장됨)이 있는 API 프록시가 버전 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에 남아 있지만 특정 생성자 또는 메서드 서명이 삭제, 지원 중단 또는 변경되었습니다 (예: org.w3c.dom.Document 및 관련 XML 파싱 클래스의 특정 DOM 파싱 메서드).

    도구 감지: 변경 감지 도구는 METHOD_SIGNATURE_MODIFICATION 카테고리에서 이러한 클래스에 대한 참조에 MEDIUM 영향 확실성 플래그를 지정하여 개발자가 수정된 메서드 호출에 대한 콜아웃의 소스 코드를 검사하도록 유도합니다.

해결 전략

업그레이드하기 전에 Java 콜아웃 정책과 커스텀 JAR 리소스가 Java 21 런타임과 호환되는지 확인하세요. 변경 감지 도구를 사용하면 클러스터 전체에서 영향을 받는 API 프록시, 공유 흐름, 환경 또는 조직 JAR 리소스를 식별할 수 있습니다.

이 섹션에서 설명하는 해결 전략은 일반적인 가이드이며 상호 배타적이지 않습니다. 운영 요구사항에 따라 전략을 결합할 수 있습니다. 예를 들어 전략 2를 사용하여 콜아웃 소스 코드를 현대화하고 전략 3B를 사용하여 업데이트된 프록시 버전을 배포하여 메시지 프로세서 업그레이드 중에 다운타임을 없앨 수 있습니다.

전략 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을 번들로 묶을 수 없음 전략 3B: 새 환경 만들기 (다운타임 없는 마이그레이션) 트래픽 중단 없이 마이그레이션 중에 4.53 및 4.54 노드를 격리합니다. 임시 메시지 프로세서 노드 조달 필요
아니요 (운영 접근 방식) 업그레이드 전에는 프록시 번들을 수정할 수 없음 * 전략 3C: 노드 수준 external-lib 배치 프록시 번들을 수정하지 않고 누락된 라이브러리 JAR을 노드 전체에 제공 노드의 모든 프록시에서 공유되며 리플렉션 또는 java.* 패키지를 해결하지 않음
아니요 (비공개 소스 서드 파티 라이브러리) Java 내부에서 리플렉션을 사용하는 서드 파티 공급업체 라이브러리 * 전략 4: JVM 플래그 (--add-opens / --add-exports) 내부 Java 패키지의 리플렉션 제한 완화 삭제된 클래스 또는 메서드를 복원할 수 없습니다. 노드 전체에 적용됩니다.

전략 1: 번들 JAR을 통한 이중 호환 프록시 (업그레이드 전에 테스트하여 다운타임 없음)

사용 시기: 다음과 같은 경우에 이 전략을 사용합니다.

  • 이중 호환 독립형 대체 라이브러리 사용 가능: 필요한 기능을 구현하고 소스 코드 수정 없이 API 프록시에 직접 번들로 묶을 수 있는 대체 JAR이 있습니다.
  • 기존 API 프록시와 Java 콜아웃이 현재 버전 (예: 프라이빗 클라우드용 Edge 4.53.01)과 업그레이드된 버전 (프라이빗 클라우드용 Edge 4.54.00) 모두에서 원활하게 작동하기를 원합니다.
  • 프라이빗 클라우드용 Edge 클러스터를 업그레이드하기 전에 스테이징 및 프로덕션 환경의 모든 변경사항을 테스트하고 확인하여 실시간 트래픽에서 예기치 않은 문제와 다운타임이 발생하지 않도록 합니다.
  • Java 콜아웃 비즈니스 로직을 다시 작성하거나 리팩터링하지 않으려고 합니다.

작동 방식: Java 8에서는 특정 라이브러리 (예: JAXB javax.xml.bind.* 또는 Activation javax.activation.*)가 Java 8 런타임에 직접 빌드되었습니다. 따라서 개발자는 프록시 번들 내에 추가 JAR 파일을 포함할 필요가 없었습니다. Java 21에서는 이러한 라이브러리가 Java 런타임에서 삭제되었습니다.

프라이빗 클라우드용 Edge 4.53.x 및 4.54.00에서 프록시를 '이중 호환'되도록 하려면 다음 단계를 따르세요.

  1. 호출에 필요한 누락된 라이브러리 (예: JAXB 또는 활성화)를 식별합니다.
  2. 독립형 오픈소스 대체 JAR (예: jakarta.xml.bind-api-2.3.3.jar 및 jaxb-runtime-2.3.8.jar)을 가져옵니다.
  3. 대체 JAR을 apiproxy/resources/java/ 아래의 프록시 번들에 직접 배치하거나 프록시 수준 리소스 파일 API를 사용하여 프록시 수정사항에 업로드하거나 환경 수준 또는 조직 수준에서 리소스 파일로 업로드합니다. 리소스 파일 관리에 대한 자세한 내용은 Apigee 리소스 파일 문서를 참조하세요.
  4. 업그레이드 전에 배포 및 테스트: 프라이빗 클라우드용 Edge 4.53.x 및 4.54.00의 메시지 프로세서는 번들로 제공되는 JAR에서 클래스를 로드합니다. 이제 이 업데이트된 프록시 번들을 배포하고 현재 프라이빗 클라우드용 Edge 4.53.x 클러스터에서 합성 트래픽으로 테스트할 수 있습니다.
  5. 메시지 프로세서에서 외부 허용 패키지 로드 사용 설정 (4.54.00에 필요): 프라이빗 클라우드용 Edge 4.54.00에서는 기본적으로 외부 또는 번들 리소스 JAR에서 삭제된 Java 패키지 (예: javax.xml.bind.* 및 javax.activation.*)를 로드하는 기능이 사용 중지되어 있으므로 (conf_system_java.21.enable.external.allowed.packages=false) JAR만 번들로 묶는 것은 기본적으로 작동하지 않습니다. 구성으로 코드 작성(CwC)을 사용하여 /opt/apigee/customer/application/message-processor.properties에서 이 속성을 사용 설정해야 합니다. 메시지 프로세서 노드를 업그레이드하기 전에 이 속성을 구성하거나 업그레이드한 후 설정하고 메시지 프로세서를 다시 시작할 수 있습니다. 
    conf_system_java.21.enable.external.allowed.packages=true
  6. 업그레이드 후 실시간 트래픽 문제 없음: 이후 클러스터가 conf_system_java.21.enable.external.allowed.packages=true가 사용 설정된 프라이빗 클라우드용 Edge 4.54.00으로 업그레이드되면 메시지 프로세서에 이미 필요한 JAR이 있고 실패 없이 번들 리소스 파일에서 클래스를 로드하므로 (NoClassDefFoundError) 다운타임 없이 원활하게 업그레이드할 수 있습니다.

코드 예시: 주문 XML 유효성 검사 및 파싱 콜아웃

JAXB (JAXBContext 및 Unmarshaller)를 사용하여 수신 XML 주문을 추출하고 검증하는 일반적인 Apigee Java 콜아웃을 생각해 보세요.

  • 수정 전 (프라이빗 클라우드용 Edge 4.54.00에서 실패): 프라이빗 클라우드용 Edge 4.53.x에서 프록시 번들에는 콜아웃 JAR만 포함되어 JAXB에 내장된 Java 8 런타임 라이브러리를 사용합니다. 
    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 4.53.x에서는 문제없이 실행됩니다. 노드가 프라이빗 클라우드용 Edge 4.54.00으로 업그레이드되면 요청 처리 중에 이 프록시가 즉시 실패합니다.

    java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext
        at com.example.callout.OrderXmlParserCallout.execute(OrderXmlParserCallout.java:20)
  • 수정 후 (프라이빗 클라우드용 Edge 4.53.x 및 4.54.00에서 이중 호환): Java 콜아웃 코드를 다시 작성하거나 다시 컴파일할 필요가 없습니다. 독립형 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

      또는 프록시 수준 리소스 파일 API를 사용하거나 환경 수준 또는 조직 수준에서 jakarta.xml.bind-api-2.3.3.jar 및 jaxb-runtime-2.3.8.jar를 리소스 파일로 업로드하여 동일한 범위의 모든 프록시가 각 개별 프록시 번들에 번들로 묶지 않고도 공유할 수 있습니다.

      Maven을 사용하여 소스에서 프록시 번들을 빌드하는 경우 빌드 중에 자동으로 패키징되도록 pom.xml에서 이러한 종속 항목을 선언합니다.

    2. 현재 4.53.x 클러스터에 배포 및 테스트: 업데이트된 프록시 번들을 기존 프라이빗 클라우드용 Edge 4.53.x 환경에 배포하고 테스트 호출을 보냅니다. 프라이빗 클라우드용 Edge 4.53.x 메시지 프로세서는 이러한 번들 JAR에서 클래스를 로드하므로 콜아웃이 동일하게 계속 작동하는지 확인할 수 있습니다.
    3. CwC를 통해 외부 허용 패키지 로드 사용 설정: 프라이빗 클라우드용 Edge 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false)에서는 외부 허용 패키지 로드가 기본적으로 사용 중지되어 있으므로 구성 코딩 (CwC)을 사용하여 /opt/apigee/customer/application/message-processor.properties의 각 메시지 프로세서 노드에서 이를 사용 설정합니다. 
      conf_system_java.21.enable.external.allowed.packages=true
    4. 업그레이드 후 실시간 트래픽 문제 없음: 4.53.x 환경에서 검증되고 CwC 속성으로 구성되면 프록시가 완전히 준비됩니다. 클러스터를 프라이빗 클라우드용 Edge 4.54.00으로 업그레이드하면 메시지 프로세서가 번들로 묶인 JAXB 클래스를 로드하여 오류가 없고 실시간 트래픽 중단이 발생하지 않습니다.

전략 2: 대체 구현 (코드 및 종속 항목 현대화)

사용 시기: 프록시 소스 코드를 쉽게 유지관리할 수 있는 활성 코드베이스에 권장됩니다. 이는 Java 21 규정 준수를 위한 가장 깔끔한 장기적 접근 방식입니다. 출시 참고사항: 현대화된 프록시 버전을 배포하려면 메시지 프로세서 조정이 필요하므로 이 전략을 전략 3A (계획된 유지보수 기간 중) 또는 전략 3B (병렬 메시지 프로세서로 다운타임 없음)와 함께 사용하세요.

작동 방식: 삭제된 Java 내부 클래스를 공식 표준 Java SE API 또는 오픈소스 독립형 상응 항목으로 대체하고 필요한 서드 파티 종속 항목을 프록시 번들 리소스 파일 또는 POM 내에 직접 패키징합니다.

코드 예시:

예시 1: 메서드 및 코드 현대화 (삭제된 내부 유틸리티 대체)

Java 8에서 콜아웃은 sun.misc.BASE64Encoder과 같은 내부 유틸리티 클래스를 자주 사용했습니다. 최신 Java에서는 이러한 클래스가 삭제되었지만 표준 java.util.Base64 API는 외부 종속 항목 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;
    }
}
  • After (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 네임스페이스 프리픽스 매퍼)

Java 8에서 XML 네임스페이스 프리픽스를 맞춤설정하는 API 프록시는 일반적으로 Sun의 내부 JAXB 매퍼 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;
    }
}
  • After (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): 런타임에 이 클래스를 제공하려면 apiproxy/resources/java/ 내에 독립형 JAXB 라이브러리를 번들로 묶거나 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>

전략 3A: 계획된 유지보수 다운타임 (인플레이스 재배포)

사용 시기: 짧은 서비스 중단이 허용되는 예약된 운영 유지보수 기간이 있는 환경에 권장됩니다.

절차:

  1. API 소비자와 예약된 유지보수 기간을 조정합니다.
  2. 업그레이드 경로 가이드에 따라 프라이빗 클라우드용 Edge 구성요소를 버전 4.54.00으로 업그레이드합니다.
  3. New Edge UI 또는 Apigee Management API (배포)를 사용하여 사전 컴파일된 4.54.00 호환 버전의 API 프록시를 배포합니다.
  4. 메시지 프로세서에 합성 테스트 요청을 전송하고 Trace 도구를 사용하여 로그를 검사하여 콜아웃 실행을 확인합니다.
  5. 유지보수 기간을 종료하고 공개 트래픽을 다시 엽니다.

전략 3B: 새 환경 만들기 (다운타임 없는 마이그레이션)

사용 시기: 다운타임이 제로여야 하는 미션 크리티컬 프로덕션 환경에 권장됩니다. Java 콜아웃을 Java 8과 Java 21에서 동시에 작동하도록 업데이트할 수 없는 경우에 사용합니다.

작동 방식: 이 전략에는 다양한 버전의 메시지 프로세서 노드를 연결할 수 있도록 하나 이상의 새 환경을 조달하는 것이 포함됩니다. 그런 다음 Java 8 호환 프록시를 4.53.X 메시지 프로세서로 연결된 환경에 배포하고 Java 21 호환 프록시를 4.54.00 메시지 프로세서로 연결된 환경에 배포합니다. 그런 다음 부하 분산기 또는 기타 라우팅 기술을 사용하여 Java 21 호환 프록시로만 트래픽을 라우팅합니다.

이 전략의 경우 조직, 환경, 메시지 프로세서가 상호작용하는 방식을 이해하는 것이 다운타임 없는 컷오버의 핵심입니다. 자세한 내용은 Apigee Edge 조직 구조를 참조하세요.

  • Apigee 조직은 여러 환경 (예: prod, test)을 포함하는 최상위 관리 경계입니다.
  • API 프록시 버전은 특정 환경에 배포됩니다. 해당 환경에 명시적으로 바인딩된 메시지 프로세서만 프록시 버전을 로드하고 실행합니다.
+------------------------------------------------------------------------+
|                          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 메시지 프로세서 노드 프로비저닝: 새 VM 인스턴스 또는 임시 VM 인스턴스에 프라이빗 클라우드용 Edge 4.54.00을 설치하고 이러한 노드를 prod-migration에 바인딩합니다 (메시지 프로세서 추가 참조).
  3. 영향을 받는 프록시 식별 및 업데이트된 버전 만들기: Java 콜아웃을 사용하여 API 프록시를 식별하고 (변경 감지 도구 사용) 영향을 받는 각 프록시의 새 버전을 프라이빗 클라우드용 Edge 4.54.00 호환 Java 콜아웃으로 만듭니다 (전략 1 또는 전략 2 적용).
  4. 현대화된 프록시 버전을 임시 환경에 배포: 업데이트된 호환 프록시 버전을 prod-migration에만 배포합니다.
  5. 트래픽 확인 및 전환: 새 가상 호스트에 대해 합성 확인 테스트를 실행합니다. 확인되면 클라이언트 트래픽을 prod에서 prod-migration로 리디렉션하도록 외부 부하 분산기 (F5, NGINX)를 구성합니다.
  6. 원래 노드 업그레이드 및 다시 전환: prod에서 기존 프록시를 배포 취소합니다. 업그레이드 경로 가이드에 따라 원래 메시지 프로세서 노드를 4.54.00으로 업그레이드합니다. 현대화된 프록시 버전을 prod에 배포하고 부하 분산기 트래픽을 다시 prod로 리디렉션하고 작업을 확인합니다.
  7. 임시 환경 사용 중지: prod-migration에서 프록시 배포를 취소하고 임시 메시지 프로세서 노드를 삭제하고 임시 환경을 삭제합니다.

전략 3C: 노드 수준 external-lib 배치 (공유 대체 라이브러리)

사용 시기: Java 21에서 삭제된 Java 클래스를 사용하는 API 프록시가 여러 개 있고 업그레이드 전에 각 개별 프록시 번들을 다시 컴파일하거나 다시 패키징하는 것이 운영상 불가능한 경우에 권장됩니다.

작동 방식: 프라이빗 클라우드용 Edge 4.54.00에서 메시지 프로세서는 전용 노드 디렉터리($APIGEE_ROOT/data/edge-message-processor/external-lib)에서 누락된 Java 클래스를 로드하는 메커니즘을 제공합니다.

이 메커니즘을 사용 설정하면 메시지 프로세서가 기본 확인으로 대체하기 전에 이 디렉터리에서 누락된 클래스를 확인합니다. 서드 파티 라이브러리 JAR에서 누락된 클래스를 가져오거나 필수 클래스를 JAR에 번들로 묶어 external-lib에 배치하여 누락된 클래스를 제공할 수 있습니다.

절차:

  1. 각 메시지 프로세서 노드에 외부 라이브러리 디렉터리를 만듭니다. 
    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에서 클래스를 확인하고 로드할 수 있도록 하려면 구성 코드 (CwC)를 사용하여 /opt/apigee/customer/application/message-processor.properties에서 이 속성을 사용 설정해야 합니다. 
    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. 리플렉션에 사용되는 액세스할 수 없는 패키지 식별: 서드 파티 라이브러리에서 리플렉션 방식으로 액세스하는 내부 자바 모듈과 패키지를 확인합니다. 참고: 이러한 리플렉션 오류는 프라이빗 클라우드용 Edge 4.54.00의 Java 21에서만 발생하며 버전 4.53.x 로그에는 표시되지 않습니다. 업그레이드 후 메시지 프로세서 로그 (/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. 구성 파일이 포함된 코드 (CwC)를 사용하여 /opt/apigee/customer/application/message-processor.properties를 수정합니다 (파일이 없는 경우 생성).
  3. 타겟팅된 --add-opens 또는 --add-exports 플래그를 bin_setenv_ext_jvm_opts에 추가합니다. 
    # Configure targeted JVM module access for closed-source legacy callouts (enclosed in double quotes)
bin_setenv_ext_jvm_opts="-XX:+UseG1GC -XX:+AlwaysPreTouch --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/sun.misc=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED --add-opens java.base/sun.security.x509=ALL-UNNAMED"
  4. 적절한 파일 소유권 및 권한을 확인합니다. 
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
chmod 644 /opt/apigee/customer/application/message-processor.properties
  5. apigee-service를 사용하여 메시지 프로세서를 다시 시작합니다. 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

TLS 및 암호화 스위트 변경사항

프라이빗 클라우드용 Edge 4.54.00에서는 메시지 프로세서, 관리 서버, 라우터를 비롯한 핵심 플랫폼 구성요소가 Java 21 LTS에서 실행되도록 업데이트되었습니다. 이 업데이트는 TLS 1.3을 기본적으로 사용 설정 (JEP 332)하여 암호화 보안을 현대화합니다. 이제 메시지 프로세서는 TLS 1.3을 아웃바운드 백엔드 연결에 선호되는 프로토콜로 협상하고 백엔드에서 지원하지 않는 경우 TLS 1.2로 대체합니다.

기존 백엔드 요구사항 및 해결 방법

Java 21 암호화 기준은 jdk.tls.disabledAlgorithms에서 기본적으로 사용 중지된 프로토콜 및 암호화 스위트 목록을 업데이트합니다 (예: 기존 TLS 프로토콜 및 forward secrecy가 아닌 정적 RSA 키 교환 스위트: TLS_RSA_*). 자체 Java 21 런타임을 제공하므로 사용 중지된 프로토콜 및 암호화 스위트의 정확한 목록은 특정 Java 21 구현에 따라 다릅니다.

기존 API 프록시가 사용 중지된 프로토콜 또는 정적 RSA 암호화가 필요한 기존 백엔드 인프라에 연결되는 경우 다음 작업을 검토하세요.

  • 백엔드 보안 현대화 (권장): 최신 ECDHE 암호화 스위트와 함께 TLS 1.2 또는 TLS 1.3을 지원하도록 대상 서버와 부하 분산기를 업그레이드합니다. API 프록시에서 프로토콜 및 암호화 스위트를 구성하려면 Edge에서 백엔드로 TLS 구성 및 TLS/SSL TargetEndpoint 구성 참조 (또는 TargetServer를 사용하는 경우 백엔드 서버 간 부하 분산)을 참고하세요.
  • CwC를 사용하여 기존 알고리즘 다시 사용 설정 (업그레이드 중 전환 조치): 플랫폼 업그레이드 전에 백엔드 업그레이드를 완료할 수 없는 경우 구성 코드 (CwC)를 사용하여 필요한 알고리즘을 일시적으로 다시 사용 설정할 수 있습니다.
    1. Java 21 설치에서 기본 jdk.tls.disabledAlgorithms 값을 확인합니다 (예: $JAVA_HOME/conf/security/java.security).
    2. 사용 중지된 알고리즘의 동일한 목록으로 /opt/apigee/customer/application/message-processor.properties에서 conf_jvmsecurity_jdk.tls.disabledAlgorithms를 재정의하고 TLS_RSA_* 항목만 삭제합니다 (나머지 보호가 사용 설정된 상태로 유지되도록 다른 모든 사용 중지된 알고리즘은 그대로 유지).
    3. apigee-service를 사용하여 메시지 프로세서를 다시 시작합니다. 백엔드가 ECDHE 암호화 스위트를 지원하면 이 재정의를 삭제합니다.
  • 커스텀 암호화 스위트 허용 목록 업데이트: 이전에 conf_http_HTTPTransport.ssl.cipher.suites.whitelist를 재정의한 경우 업그레이드하기 전에 검토하세요. Java 21은 더 이상 정적 RSA 제품군 (TLS_RSA_*)을 지원하지 않으므로 해당 제품군만 포함하는 허용 목록은 메시지 프로세서에 사용 가능한 암호화가 없고 백엔드 호출이 no cipher suites in common로 실패합니다. TLS_RSA_* 항목을 삭제하고 Java 21 구현에서 지원하는 최신 암호화 스위트를 구성합니다. 이 속성을 재정의하지 않은 경우 4.54.00 기본값에는 이미 지원되는 제품군이 포함되어 있으므로 변경할 필요가 없습니다.
  • 내부 라우터를 메시지 프로세서 암호화로 업데이트: 이전에 정적 RSA 스위트로 conf_message-processor-communication_local.http.ssl.ciphers를 재정의한 경우 업그레이드하기 전에 Java 21 구현에서 지원하는 최신 암호화 스위트로 업데이트하세요. 그렇지 않으면 라우터가 메시지 프로세서와의 TLS 핸드셰이크를 완료할 수 없습니다. 그런 다음 메시지 프로세서를 다시 시작합니다. 
    apigee-service edge-message-processor restart
     라우터와 메시지 프로세서 간 TLS 구성을 참조하세요.

Edge 구성요소 간에 TLS를 구성하는 방법에 대한 자세한 내용은 라우터와 메시지 프로세서 간에 TLS 구성을 참조하세요.

변경 감지 도구

Apigee는 프라이빗 클라우드용 Edge 4.54.00 업그레이드의 영향을 받을 수 있는 배포된 API 프록시, 정책, 공유 흐름, 리소스 JAR에 대해 클러스터를 스캔하는 변경 감지 도구를 제공합니다.

이 도구는 Java 21과 호환되지 않는 라이브러리, 강력하게 캡슐화된 내부 API, 기존 정책 지원 중단, OpenLDAP RDN 제한 등 업그레이드를 차단할 수 있는 요소를 식별하고 적절한 수정 전략을 선택하는 데 도움이 되는 실행 가능한 보고서를 생성합니다.

전체 기본 요건, 다운로드 안내, 명령줄 문법, 샘플 보고서는 전용 변경 감지 도구 가이드를 참고하세요.