Edge for Private Cloud 4.54.00 の変更点

変更の概要

Edge for Private Cloud 4.54.00 では、プラットフォームのセキュリティ ポスチャーを強化する複数の変更が導入され、Java 21 で実行するようにプラットフォーム コンポーネントが更新されています。以下の 2 つのセクションで、これらの変更について説明します。

これらの変更に加えて、専用の変更検出ツールのガイドもご確認ください。このユーティリティは、このアップグレードの結果として中断を引き起こす可能性がある、クラスタ内のプロキシ、共有フロー、その他のアーティファクトの変更を特定するために使用できます。

Java Callout ポリシーの変更

Edge for Private Cloud 4.54.00 では、Message Processor、Management Server、Router などのコア プラットフォーム コンポーネントが Java 21 LTS で実行されるように更新されています。Java 21 は、Java プラットフォームを最新化します。これには、レガシーの Java EE モジュールと CORBA モジュール（JEP 320）の削除、レガシーの内部ユーティリティ クラスの削除、強力なモジュール式カプセル化の適用（JEP 403）が含まれます。

これらの変更により、カスタム JavaCallout ポリシーまたはカスタム リソース JAR（プロキシ、環境、または組織レベルで保存）を使用する API プロキシは、バージョン 4.54.00 へのアップグレード時に中断が発生する可能性があります。

Java Callout に影響する可能性のある変更のカテゴリ

  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 の特定の DOM 解析メソッドや関連する XML 解析クラスなど）。

    ツールの検出: 変更検出ツールは、METHOD_SIGNATURE_MODIFICATION カテゴリのこれらのクラスへの参照に MEDIUM 影響の確実性のフラグを設定し、デベロッパーがコールアウトのソースコードで変更されたメソッド呼び出しを検査するように促します。

修復戦略

アップグレードする前に、Java Callout ポリシーとカスタム JAR リソースが Java 21 ランタイムと互換性があることを確認してください。変更検出ツールを使用すると、クラスタ全体で影響を受ける API プロキシ、共有フロー、環境または組織の JAR リソースを特定できます。

このセクションで説明する修復戦略は一般的なガイドであり、相互に排他的なものではありません。運用要件に応じて、戦略を組み合わせることができます。たとえば、戦略 2 を使用してコールアウト ソースコードをモダナイズし、戦略 3B を使用して更新されたプロキシ リビジョンをデプロイすることで、Message Processor のアップグレード中にダウンタイムをゼロにできます。

戦略 3A、3B、3C は、同じ運用アプローチを実行する 3 つの方法です。つまり、プロキシ バンドルを変更せずに、ノードのアップグレードとプロキシの再デプロイを異なるタイミングで行います。API の可用性の要件に基づいて、これらのいずれかまたは組み合わせを選択します。

次の決定ガイドを確認して、デプロイに最適なアプローチを選択してください。

Java Callout の緩和策に関する意思決定ガイド:

プロキシ バンドルの更新と再デプロイが必要か？ シナリオまたは要件 推奨される戦略 解決できる課題 主な制限事項
はい（バンドル アップデートのみ） デュアル互換ライブラリが存在する。ダウンタイムをゼロにする必要がある 戦略 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 ノードを分離する 一時的な Message Processor ノードの調達が必要
いいえ（運用アプローチ） アップグレード前にプロキシ バンドルを変更できない * 戦略 3C: ノードレベルの外部ライブラリの配置 プロキシ バンドルを編集せずに、不足しているライブラリ JAR をノード全体に提供する ノード上のすべてのプロキシで共有。リフレクションまたは java.* パッケージを解決しない
いいえ（クローズドソースのサードパーティ ライブラリ） Java 内部でリフレクションを使用するサードパーティ ベンダー ライブラリ * 戦略 4: JVM フラグ（--add-opens / --add-exports） 内部 Java パッケージのリフレクション制限を緩和します。 削除されたクラスやメソッドを復元できない。ノード全体に適用される

戦略 1: バンドルされた JAR を介したデュアル互換プロキシ（アップグレード前にテストしてダウンタイムをゼロにする）

使用に適したケース: この戦略は、次のような場合に使用します。

  • デュアル互換のスタンドアロン置換ライブラリが利用可能: 必要な機能を実装する置換 JAR が存在し、ソースコードを変更することなく API プロキシに直接バンドルできます。
  • 既存の API プロキシと Java Callout が、現在のバージョン（Edge for Private Cloud 4.53.01 など）とアップグレード バージョン（Edge for Private Cloud 4.54.00）の両方でシームレスに動作するようにします。
  • Edge for Private Cloud クラスタをアップグレードする前に、ステージング環境と本番環境ですべての変更をテストして検証し、予期しない問題やライブ トラフィックのダウンタイムが発生しないようにします。
  • Java Callout のビジネス ロジックの書き換えやリファクタリングを回避したい。

仕組み: Java 8 では、特定のライブラリ（JAXB javax.xml.bind.* や Activation javax.activation.* など）が Java 8 ランタイムに直接組み込まれていました。このため、デベロッパーはプロキシ バンドル内に追加の JAR ファイルを含める必要がありませんでした。Java 21 では、これらのライブラリは Java ランタイムから削除されました。

Edge for Private Cloud 4.53.x と 4.54.00 の両方に対応する「デュアル互換」プロキシを作成するには:

  1. コールアウトに必要な欠落しているライブラリ（JAXB や Activation など）を特定します。
  2. スタンドアロンのオープンソースの代替 JAR（jakarta.xml.bind-api-2.3.3.jar や jaxb-runtime-2.3.8.jar など）を取得します。
  3. 置換 JAR を apiproxy/resources/java/ の下のプロキシ バンドルに直接配置するか、プロキシレベルの Resource Files API を使用してプロキシ リビジョンにアップロードするか、環境レベルまたは組織レベルでリソース ファイルとしてアップロードします。リソース ファイルの管理について詳しくは、Apigee リソース ファイルのドキュメントをご覧ください。
  4. アップグレード前にデプロイしてテストする: Edge for Private Cloud 4.53.x と 4.54.00 の両方の Message Processor は、これらのバンドルされた JAR からクラスを読み込みます。この更新されたプロキシ バンドルをデプロイして、現在の Edge for Private Cloud 4.53.x クラスタで合成トラフィックを使用してテストできます。
  5. Message Processor で外部の許可されたパッケージの読み込みを有効にする（4.54.00 で必須）: Edge for Private Cloud 4.54.00 では、デフォルトで、削除された Java パッケージ（javax.xml.bind.* や javax.activation.* など）を外部またはバンドルされたリソース JAR から読み込むことが無効になっています（conf_system_java.21.enable.external.allowed.packages=false）。そのため、JAR をバンドルするだけではデフォルトで機能しません。コード構成（CwC）を使用して、/opt/apigee/customer/application/message-processor.properties でこのプロパティを有効にする必要があります（このプロパティは、Message Processor ノードをアップグレードする前に構成することも、アップグレード後に設定して Message Processor を再起動することもできます）。
    conf_system_java.21.enable.external.allowed.packages=true
  6. アップグレード後のライブ トラフィックの問題がゼロ: その後、conf_system_java.21.enable.external.allowed.packages=true を有効にしてクラスタを Edge for Private Cloud 4.54.00 にアップグレードすると、Message Processor には必要な JAR がすでに用意されており、バンドルされたリソース ファイルからクラスが問題なく読み込まれます（NoClassDefFoundError）。これにより、ダウンタイムなしでスムーズにアップグレードできます。

コード例: 注文 XML の検証と解析のコールアウト

JAXB（JAXBContext と Unmarshaller）を使用して受信 XML 注文を抽出して検証する一般的な Apigee Java Callout を考えてみましょう。

  • 修正前（Edge for Private Cloud 4.54.00 で失敗）: Edge for Private Cloud 4.53.x では、プロキシ バンドルにはコールアウト JAR のみが含まれており、JAXB には組み込みの Java 8 ランタイム ライブラリが使用されています。
    apiproxy/
  resources/
    java/
      OrderXmlParserCallout.jar   <-- No JAXB JAR bundled

    Java Callout の実装:

    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 for Private Cloud 4.53.x では、問題なく実行されます。ノードが Edge for Private Cloud 4.54.00 にアップグレードされると、このプロキシはリクエスト処理中にすぐに失敗します。

    java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext
        at com.example.callout.OrderXmlParserCallout.execute(OrderXmlParserCallout.java:20)
  • 修正後（Edge for Private Cloud 4.53.x と 4.54.00 の両方に対応）: Java Callout コードを書き換えたり、再コンパイルしたりする必要はありません。スタンドアロン JAR を提供することで、プロキシを直接デュアル互換にすることができます。
    1. スタンドアロン JAR を直接バンドルまたはアップロードする: スタンドアロン JAXB ライブラリ（jakarta.xml.bind-api-2.3.3.jar と jaxb-runtime-2.3.8.jar）を取得し、プロキシ バンドルの apiproxy/resources/java/ の下に配置します。
      apiproxy/
  resources/
    java/
      OrderXmlParserCallout.jar
      jakarta.xml.bind-api-2.3.3.jar
      jaxb-runtime-2.3.8.jar

      または、プロキシレベルの Resource Files API を使用して、jakarta.xml.bind-api-2.3.3.jar と jaxb-runtime-2.3.8.jar をリソース ファイルとしてアップロードするか、環境レベルまたは組織レベルでアップロードします。これにより、同じスコープのすべてのプロキシが、個々のプロキシ バンドルにバンドルすることなく、それらを共有できます。

      Maven を使用してソースからプロキシ バンドルをビルドする場合は、これらの依存関係を pom.xml で宣言して、ビルド中に自動的にパッケージ化されるようにします。

    2. 現在の 4.53.x クラスタにデプロイしてテストする: 更新されたプロキシ バンドルを既存の Edge for Private Cloud 4.53.x 環境にデプロイし、テスト呼び出しを送信します。Edge for Private Cloud 4.53.x Message Processor は、これらのバンドルされた JAR からクラスを読み込むため、コールアウトが引き続き同じように機能することを確認できます。
    3. CwC を介して外部の許可されたパッケージの読み込みを有効にする: Edge for Private Cloud 4.54.00（conf_system_java.21.enable.external.allowed.packages=false）では、外部の許可されたパッケージの読み込みはデフォルトで無効になっているため、構成を含むコード（CwC）を使用して、/opt/apigee/customer/application/message-processor.properties の各 Message Processor ノードで有効にします。
      conf_system_java.21.enable.external.allowed.packages=true
    4. アップグレード後のライブ トラフィックの問題がゼロ: 4.53.x 環境で検証され、CwC プロパティで構成されると、プロキシの準備が完了します。クラスタを Edge for Private Cloud 4.54.00 にアップグレードすると、Message Processor はバンドルされた JAXB クラスを読み込み、エラーとライブ トラフィックの中断をゼロにします。

戦略 2: 代替実装（コードと依存関係のモダナイゼーション）

使用する場合: プロキシのソースコードが容易にメンテナンスされるアクティブなコードベースにおすすめします。これは、Java 21 への準拠を長期的に維持するための最もクリーンなアプローチです。ロールアウトに関する注: モダナイズされたプロキシ リビジョンのデプロイには Message Processor の調整が必要なため、この戦略を戦略 3A（計画されたメンテナンスの時間枠内）または戦略 3B（並列 Message Processor でダウンタイムをゼロにする）と組み合わせます。

仕組み: 削除された 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;
    }
}
  • 後（Java 21 準拠の実装）:
    // Fully compatible with Java 21: uses standard Java SE java.util.Base64 (no external JARs needed)
import java.util.Base64;
// other required imports

public class Base64EncodeCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        String encoded = Base64.getEncoder().encodeToString("ApigeePayload".getBytes());
        messageContext.setVariable("encoded_data", encoded);
        return ExecutionResult.SUCCESS;
    }
}
例 2: バンドルされたライブラリ（JAXB Namespace Prefix Mapper）を使用したインポート レベルのリファクタリング

Java 8 では、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 で同じクラスを提供します。すべてのメソッド シグネチャ、パラメータ、戻り値の型は同じです。コードの変更は厳密に import ステートメントで行われます。

  • 変更前（以前の Java 8 実装）:
    // In Java 8: Relied on internal Sun class in Java 8 runtime
import com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper;
public class CustomNamespaceMapper extends NamespacePrefixMapper {
    @Override
    public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
        if ("http://schemas.example.com/orders".equals(namespaceUri)) {
            return "ord";
        }
        return suggestion;
    }
}
  • 後（Java 21 準拠の実装）:
    // In Java 21: Identical methods and logic; ONLY the import statement changes (".internal." removed)
import com.sun.xml.bind.marshaller.NamespacePrefixMapper;
public class CustomNamespaceMapper extends NamespacePrefixMapper {
    @Override
    public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
        if ("http://schemas.example.com/orders".equals(namespaceUri)) {
            return "ord";
        }
        return suggestion;
    }
}
  • バンドルされた依存関係の構成（pom.xml）: 実行時にこのクラスを提供するには、スタンドアロンの JAXB ライブラリを apiproxy/resources/java/ 内にバンドルするか、pom.xml で宣言します。
    <dependencies>
    <!-- Standalone JAXB API for Java 21 -->
    <dependency>
        <groupId>jakarta.xml.bind</groupId>
        <artifactId>jakarta.xml.bind-api</artifactId>
        <version>2.3.3</version>
    </dependency>
    <!-- Standalone JAXB Runtime providing com.sun.xml.bind.marshaller.NamespacePrefixMapper -->
    <dependency>
        <groupId>org.glassfish.jaxb</groupId>
        <artifactId>jaxb-runtime</artifactId>
        <version>2.3.8</version>
    </dependency>
</dependencies>

戦略 3A: 計画的なメンテナンスによるダウンタイム（インプレース再デプロイ）

使用する場合: 短時間のサービス中断が許容される、運用メンテナンスの時間枠がスケジュールされている環境におすすめします。

手順:

  1. API コンシューマーとスケジュールされたメンテナンスの時間枠を調整する。
  2. アップグレード パスガイドに沿って、Edge for Private Cloud コンポーネントをバージョン 4.54.00 にアップグレードします。
  3. 新しい Edge UI または Apigee Management API（Deployments）を使用して、4.54.00 互換のプリコンパイル済み API プロキシ リビジョンをデプロイします。
  4. Message Processor に合成テスト リクエストを送信し、Trace ツールを使用してログを検査することで、コールアウトの実行を確認します。
  5. メンテナンスの時間枠を終了し、パブリック トラフィックを再開します。

戦略 3B: 新しい環境を作成する（ゼロ ダウンタイムでの移行）

使用する場面: ダウンタイムをゼロにする必要があるミッション クリティカルな本番環境におすすめです。Java 8 と Java 21 の両方で同時に動作するように Java Callout を更新できない場合に使用します。

仕組み: この戦略では、1 つ以上の新しい環境を調達して、異なるバージョンの Message Processor ノードを接続できるようにします。その後、Java 8 互換のプロキシを 4.53.X Message Processor に接続された環境にデプロイし、Java 21 互換のプロキシを 4.54.00 Message Processor に接続された環境にデプロイします。次に、ロードバランサまたはその他のルーティング手法を使用して、Java 21 互換プロキシにのみトラフィックをルーティングします。

この戦略では、組織、環境、Message Processor の相互作用を理解することが、ダウンタイムなしのカットオーバーの鍵となります（詳細については、Apigee Edge の組織構造をご覧ください）。

  • Apigee 組織は、複数の環境（prod、test など）を含む最上位の管理境界です。
  • API プロキシ リビジョンは、特定の環境にデプロイされます。その環境に明示的にバインドされている Message Processor のみが、プロキシ リビジョンを読み込んで実行します。
+------------------------------------------------------------------------+
|                          Apigee Organization                           |
|                                                                        |
|  Existing Environment (prod)            Temporary Env (prod-migration) |
|  +--------------------------------+     +----------------------------+ |
|  | Current 4.53.01 MP Nodes       |     | New 4.54.00 MP Nodes       | |
|  |               |                |     |              |             | |
|  | Proxy Rev N (4.53.01)          |     | Proxy Rev N+1 (Modernized) | |
|  +--------------------------------+     +----------------------------+ |
+------------------------------------------------------------------------+
                   ^                                    ^
                   | Step 1: Normal Live                | Step 2: Canary
                   |         Traffic (prod)             | Step 3: Complete
          +------------------------------------------------------+
          |       Upstream Load Balancer / Ingress Router        |
          +------------------------------------------------------+

手順:

  1. 一時的な環境を作成する: 専用の仮想ホストとポートを使用して、組織内に新しい環境（prod-migration など）を作成します（仮想ホストと環境の設定を参照）。
  2. 4.54.00 Message Processor ノードをプロビジョニングする: 新しい VM インスタンスまたは一時的な VM インスタンスに Edge for Private Cloud 4.54.00 をインストールし、これらのノードを prod-migration にバインドします（Message Processor の追加を参照）。
  3. 影響を受けるプロキシを特定し、更新されたリビジョンを作成する: Java Callout を使用している API プロキシを特定し（変更検出ツールを使用）、影響を受ける各プロキシの新しいリビジョンを、Edge for Private Cloud 4.54.00 互換の Java Callout を使用して作成します（戦略 1 または戦略 2 を適用）。
  4. モダナイズされたプロキシ リビジョンを一時環境にデプロイする: 更新された互換性のあるプロキシ リビジョンを prod-migration にのみデプロイします。
  5. トラフィックの検証と移行: 新しい仮想ホストに対して合成検証テストを実行します。確認したら、クライアント トラフィックを prod から prod-migration にリダイレクトするように外部ロードバランサ（F5、NGINX）を構成します。
  6. 元のノードをアップグレードして切り替える: prod から以前のプロキシのデプロイを解除します。アップグレード パスガイドに沿って、元の Message Processor ノードを 4.54.00 にアップグレードします。モダナイズされたプロキシ リビジョンを prod にデプロイし、ロードバランサのトラフィックを prod にリダイレクトして、オペレーションを検証します。
  7. 一時環境を廃止する: prod-migration からプロキシをデプロイ解除し、一時的な Message Processor ノードを削除して、一時環境を削除します。

戦略 3C: ノードレベルの external-lib の配置（共有フォールバック ライブラリ）

使用する場合: Java 21 で削除された Java クラスに依存する複数の API プロキシがあり、アップグレード前に個々のプロキシ バンドルを再コンパイルまたは再パッケージ化することが運用上不可能な場合に推奨されます。

仕組み: Edge for Private Cloud 4.54.00 では、Message Processor は、専用のノード ディレクトリ $APIGEE_ROOT/data/edge-message-processor/external-lib から、欠落している Java クラスを読み込むメカニズムを提供します。

このメカニズムが有効になっている場合、Message Processor は、デフォルトの解決にフォールバックする前に、このディレクトリで欠落しているクラスを確認します。不足しているクラスは、サードパーティのライブラリ JAR から取得するか、必要なクラスを JAR にバンドルして external-lib に配置することで提供できます。

手順:

  1. 各 Message Processor ノードに外部ライブラリ ディレクトリを作成します。 
    mkdir -p /opt/apigee/data/edge-message-processor/external-lib
  2. 必要な JAR をディレクトリに配置する: 必要なクラスを含む JAR ファイルを /opt/apigee/data/edge-message-processor/external-lib にコピーします。
  3. 適切なファイルへのアクセス許可を設定する: apigee サービス ユーザーに読み取り権限があることを確認します。
    chown -R apigee:apigee /opt/apigee/data/edge-message-processor/external-lib
chmod 755 /opt/apigee/data/edge-message-processor/external-lib
chmod 644 /opt/apigee/data/edge-message-processor/external-lib/*.jar
  4. Message Processor 構成で外部パッケージの読み込みを有効にする: Edge for Private Cloud 4.54.00 では、デフォルトで外部の許可されたパッケージの読み込みが無効になっています（conf_system_java.21.enable.external.allowed.packages=false）。Message Processor が /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. Message Processor を再起動します。
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

戦略 4: JVM フラグ（--add-opens / --add-exports - 注意と最終手段）

使用する場合: この戦略は、ソースコードが利用できず、ベンダーが Java 21 のアップデートをリリースしておらず、JAR が内部 Java パッケージへのリフレクション アクセスに厳密に依存しているクローズドソースのサードパーティ ベンダー ライブラリの最後の手段として使用します。

手順:

  1. リフレクションに使用されているアクセスできないパッケージを特定する: サードパーティ ライブラリによってリフレクションでアクセスされている内部 Java モジュールとパッケージを特定します。注: これらのリフレクション エラーは、Edge for Private Cloud 4.54.00 の Java 21 でのみ発生し、バージョン 4.53.x のログには表示されません。アップグレード後の Message Processor のログ（/opt/apigee/var/log/edge-message-processor/system.log）で、必要なモジュールとパッケージを識別する InaccessibleObjectException を確認します。
    java.lang.reflect.InaccessibleObjectException: Unable to make field private final byte[] java.lang.String.value accessible: module java.base does not "opens java.lang" to unnamed module
  2. Code with Config（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 を使用して Message Processor を再起動します。
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

TLS と暗号スイートの変更

Edge for Private Cloud 4.54.00 では、Message Processor、Management Server、Router などのコア プラットフォーム コンポーネントが Java 21 LTS で実行されるように更新されています。このアップデートでは、TLS 1.3 をデフォルトで有効にすることで（JEP 332）、暗号セキュリティを最新化します。Message Processor は、アウトバウンド バックエンド接続の優先プロトコルとして TLS 1.3 をネゴシエートするようになりました。バックエンドが TLS 1.3 をサポートしていない場合は、TLS 1.2 にフォールバックします。

レガシー バックエンドの要件と修正

Java 21 の暗号化ベースラインでは、jdk.tls.disabledAlgorithms でデフォルトで無効になっているプロトコルと暗号スイートのリスト（以前の TLS プロトコルや前方秘匿性のない静的 RSA 鍵交換スイート（TLS_RSA_*）など）が更新されます。独自の Java 21 ランタイムを指定するため、無効になっているプロトコルと暗号スイートの正確なリストは、特定の Java 21 実装によって異なります。

既存の API プロキシが、無効なプロトコルまたは静的 RSA 暗号を必要とする以前のバックエンド インフラストラクチャに接続している場合は、次のアクションを確認してください。

  • バックエンド セキュリティをモダナイズする（推奨）: ターゲット サーバーとロードバランサをアップグレードして、最新の ECDHE 暗号スイートで TLS 1.2 または TLS 1.3 をサポートします。API プロキシでプロトコルと暗号スイートを構成するには、Edge からバックエンドへの TLS の構成と TLS/SSL TargetEndpoint 構成リファレンス（TargetServers を使用している場合はバックエンド サーバー間のロード バランシング）をご覧ください。
  • CwC を使用して以前のアルゴリズムを再度有効にする（アップグレード中の移行措置）: プラットフォームのアップグレード前にバックエンドのアップグレードを完了できない場合は、コードと構成（CwC）を使用して、必要なアルゴリズムを一時的に再度有効にできます。
    1. Java 21 のインストール（$JAVA_HOME/conf/security/java.security など）でデフォルトの jdk.tls.disabledAlgorithms 値を確認します。
    2. /opt/apigee/customer/application/message-processor.properties の conf_jvmsecurity_jdk.tls.disabledAlgorithms を、無効なアルゴリズムの同じリストでオーバーライドし、TLS_RSA_* エントリのみを削除します（他の無効なアルゴリズムはすべてそのままにして、残りの保護を有効にします）。
    3. apigee-service を使用して Message Processor を再起動します。バックエンドが ECDHE 暗号スイートをサポートしたら、このオーバーライドを削除します。
  • カスタム暗号スイートの許可リストを更新する: 以前に conf_http_HTTPTransport.ssl.cipher.suites.whitelist をオーバーライドした場合は、アップグレードする前に確認してください。Java 21 では、静的 RSA スイート（TLS_RSA_*）がサポートされなくなりました。そのため、これらのスイートのみを含む許可リストを使用すると、Message Processor で使用可能な暗号がなくなり、バックエンド呼び出しが no cipher suites in common で失敗します。TLS_RSA_* エントリを削除し、Java 21 実装でサポートされている最新の暗号スイートを構成します。このプロパティをオーバーライドしていない場合、4.54.00 のデフォルトにはサポートされているスイートがすでに含まれているため、変更は必要ありません。
  • 内部ルーターを Message Processor の暗号に更新する: 以前に conf_message-processor-communication_local.http.ssl.ciphers を静的 RSA スイートでオーバーライドした場合は、アップグレード前に Java 21 実装でサポートされている最新の暗号スイートで更新します。更新しないと、ルーターは Message Processor との TLS handshake を完了できません。次に、Message Processor を再起動します。
    apigee-service edge-message-processor restart
     Router と Message Processor 間の TLS の構成をご覧ください。

Edge コンポーネント間の TLS の構成の詳細については、Router と Message Processor 間の TLS の構成をご覧ください。

変更検出ツール

Apigee には、Edge for Private Cloud 4.54.00 へのアップグレードの影響を受ける可能性のあるデプロイ済みの API プロキシ、ポリシー、共有フロー、リソース JAR をクラスタでスキャンする変更検出ツールが用意されています。

このツールは、Java 21 と互換性のないライブラリ、強力にカプセル化された内部 API、サポートが終了したレガシー ポリシー、OpenLDAP RDN の制限など、アップグレードの潜在的な阻害要因を特定し、適切な修正戦略を選択するのに役立つ実用的なレポートを生成します。

前提条件、ダウンロード手順、コマンドライン構文、サンプル レポートの詳細については、専用の変更検出ツールガイドをご覧ください。