Edge for Private Cloud 4.53.01 の変更点

変更の概要

Edge for Private Cloud 4.53.01 では、ソフトウェア/ライブラリの更新バージョンを組み込み、プラットフォームのセキュリティ体制を強化する複数の変更が導入されました。これらの変更は以下に影響します。

  • OAS（OpenAPI 仕様）検証ポリシー
  • JSONPath クエリをサポートするポリシー
  • 非推奨のライブラリに依存する Java Callout ポリシー
  • OpenLDAP

このセクションでは、アップグレード中またはアップグレード後にワークフローを中断する可能性があるバージョン 4.53.01 で導入されたさまざまな種類の変更について説明します。問題が発生する可能性のある領域を特定する方法や、軽減策や回避策の方法についても説明します。

OAS（OpenAPI 仕様）検証ポリシー

コンテキスト

OAS 検証ポリシーは、OpenAPI 3.0 仕様（JSON または YAML）で定義されたルールに対して受信リクエストまたはレスポンスを検証します。Edge for Private Cloud 4.53.01 では、API レスポンス本文のより厳格で正確な検証に重点を置いた OAS（OpenAPI 仕様）ポリシーの機能強化が提供されます。

変更点

Edge for Private Cloud 4.53.01 では、OAS ポリシーによる API レスポンスの検証方法に 2 つの重要な変更が導入され、OpenAPI 仕様との整合性がより高くなっています。

  • シナリオ 1:
    • 以前の動作: OpenAPI 仕様でレスポンス本文が必要とされているにもかかわらず、ターゲットまたはアップストリーム ポリシーからの実際のレスポンスにレスポンス本文が含まれていない場合、このポリシーはこれを検証エラーとしてフラグを立てませんでした。
    • 現在の動作: このシナリオでは、ポリシーは検証エラー（例: defines a response schema but no response body found）を正しく返すようになり、想定されるレスポンスと実際のレスポンスの不一致を示します。
  • シナリオ 2:
    • 以前の動作: OpenAPI 仕様でレスポンスの本文が想定されていないことが明示的に示されているにもかかわらず、ターゲットまたはアップストリーム ポリシーからの実際のレスポンスに本文が含まれている場合、ポリシーは失敗しませんでした。
    • 現在の動作: このシナリオでは、ポリシーによりエラー（例: No response body is expected but one was found）が発生し、レスポンスが指定されたスキーマに厳密に準拠するようになります。

緩和策

Source タグが response に設定されている OAS 検証ポリシーが構成されているプロキシまたは共有フロー、またはレスポンスを生成する他のポリシーからのレスポンスを検証しているプロキシまたは共有フローを特定します。

プロキシ/共有フローが特定されたら、レスポンスと OAS 仕様の整合性を確認します。レスポンスは、レスポンス本文の有無に関して OpenAPI 仕様と厳密に一致している必要があります。標準の Apigee トレースを使用して、トラフィック パターンを確認できます。ターゲットがレスポンスを断続的に返す場合は、OAS ポリシーの前に他のポリシーを使用してレスポンスを検証します。

  • OAS 仕様ファイルでレスポンス本文が定義されている場合、ターゲット ポリシーまたはアップストリーム ポリシーからのレスポンスは常にレスポンス本文を提供する必要があります。
  • OAS 仕様ファイルでレスポンス本文が定義されていない場合、ターゲット ポリシーまたはアップストリーム ポリシーはレスポンス本文を送信してはなりません。

Private Cloud 4.53.01 へのアップグレードを試みる前に、必要に応じて OAS 検証ポリシーまたはターゲット動作を更新します。このような特定されたワークフローは、まず非本番環境で検証し、本番環境クラスタのアップグレード中の中断のリスクを最小限に抑える必要があります。

JSON パス

コンテキスト

Edge for Private Cloud 4.53.01 では、さまざまなポリシーで JSON Path 式を使用する方法が変更されました。JSONPath 式は、ExtractVariable ポリシー、RegularExpressionProtection ポリシー、データ マスキングなどのポリシーで使用して、JSON コンテンツを解析したり、変数値に値を保存したりできます。JSONPath 式は、一般的なメッセージ テンプレートでも使用できます。これにより、プロキシの実行中に変数を値に動的に置き換えることができます。新しい JSONPath 式と形式は、最新の JSON 式の標準に準拠しています。

変更点

JSONPath 式を使用するポリシーについては、既存の API プロキシ/共有フローを確認することが重要です。これには、Extract Variables ポリシー、Regular Expression Protection ポリシー、JSONPath を使用するメッセージ テンプレートを含むポリシーなどが含まれますが、これらに限定されません。

以下の JSON 入力は、変更の説明に使用されます。

{
  "store": {
    "book": [
      {"category": "reference", "author": "Nigel Rees", "price": 8.95},
      {"category": "fiction", "author": "Evelyn Waugh", "price": 12.99},
      {"category": "fiction", "author": "Herman Melville", "price": 8.99}
    ],
    "bicycle": {
      "color": "red",
      "book": [
        {"author": "Abc"}
      ]
    }
  }
}
  1. オブジェクト値の JSONPath ワイルドカード [*] の動作変更

    JSON オブジェクトのすべての直接値にアクセスするために使用される場合の [*] ワイルドカードの動作が変更されました。以前は、$.object[*] は 1 つの JSON オブジェクトにラップされた即値を返していました。ライブラリが更新されたため、出力はこれらの値を含む配列になりました。

    例: $.store[*]

    以前の動作: 
    {
  "bicycle": {
    "color": "red",
    "book": [{"author": "Abc"}]
  },
  "book": [
    {"price": 8.95, "category": "reference", "author": "Nigel Rees"},
    {"price": 12.99, "category": "fiction", "author": "Evelyn Waugh"},
    {"price": 8.99, "category": "fiction", "author": "Herman Melville"}
  ]
}
    現在の動作: 
    [
  [
    {"category": "reference", "author": "Nigel Rees", "price": 8.95},
    {"category": "fiction", "author": "Evelyn Waugh", "price": 12.99},
    {"category": "fiction", "author": "Herman Melville", "price": 8.99}
  ],
  {
    "color": "red",
    "book": [{"author": "Abc"}]
  }
]
    アクション:

    JSONPath 式を変更して、親オブジェクト（例: $.store）をターゲットに設定するだけで、以前に取得した項目を直接ターゲットに設定できるようにします。

  2. パスの JSONPath の末尾のドット (.) が原因でエラーが発生する

    JSONPath 式の検証が厳しくなっています。以前は、無効な末尾のドットで終わるパス（例: $.path.to.element.）は無視され、先行する有効なパス セグメントが一致する場合、クエリは結果を返していました。新しいバージョンでは、このような不正な形式のパスは無効として正しく識別され、エラーが発生します。

    例: $.store.book.

    以前の動作: 
    [
  {"price":8.95,"category":"reference","author":"Nigel Rees"},
  {"price":12.99,"category":"fiction","author":"Evelyn Waugh"},
  {"price":8.99,"category":"fiction","author":"Herman Melville"}
]
    現在の動作: 
    ERROR: com.jayway.jsonpath.InvalidPathException - Path must not end with a '.' or '..'

    意図しない末尾のドットを含む JSONPath 式を使用する既存のポリシーは、InvalidPathException で失敗するようになります。

    アクション:

    末尾にドットが付いている JSONPath 式から末尾のドットを削除します。たとえば、$.store.book. を $.store.book に変更します。

  3. JSONPath 再帰下降 (..) の出力構造の変更

    (..)（再帰降下）演算子を使用して名前付き要素のすべての出現箇所を特定する場合、結果の返され方が変更されています。以前は、見つかったすべての要素が 1 つのリストにフラット化されていました。更新されたライブラリは、単一のフラット リストではなく、要素が見つかった元のグループ構造を保持するリストのリストを返すようになりました。

    例: $..book

    以前の動作: 
    [
  {"price":8.95,"category":"reference","author":"Nigel Rees"},
  {"price":12.99,"category":"fiction","author":"Evelyn Waugh"},
  {"price":8.99,"category":"fiction","author":"Herman Melville"},
  {"author":"Abc"}
]
    現在の動作: 
    [
  [
    {"category":"reference","author":"Nigel Rees","price":8.95},
    {"category":"fiction","author":"Evelyn Waugh","price":12.99},
    {"category":"fiction","author":"Herman Melville","price":8.99}
  ],
  [
    {"author":"Abc"}
  ]
]
    アクション:

    新しいネストされた配列構造を考慮するように、ダウンストリーム処理ロジックを更新します。通常は、外側の JSONArray を反復処理してから、内側の各 JSONArray を反復処理して、個々の要素にアクセスする必要があります。

  4. 複数項目の選択またはフィルタ後の JSONPath インデックス作成で空の配列が返される

    インデックス（[0] など）が複数項目のセレクタ（[*] など）またはフィルタ（[?(condition)]）の直後に適用された場合の動作が変更されました。以前は、このような式は、結合された結果から指定されたインデックスの項目を選択しようとしていました。新しいバージョンでは、これらの式は空の配列（[]）を返すようになります。

    例: $.store.book[*][0]

    以前の動作: 
    {"category": "reference", "price": 8.95, "author": "Nigel Rees"}
    現在の動作: 
    []
    アクション:

    フィルタリングしてから、フィルタリングされたセットから特定の項目を取得する必要がある場合は、JSONPath によって返されたフィルタリングされた配列（たとえば $..book[?(@.category == 'fiction')]）を処理してから、前の結果から [0] を取得します。

  5. JSONPath の負の配列スライシングの出力の変更

    新しいバージョンでは、負の配列スライス（例: [-2:], [-1:]）の動作が変更されました。以前は、配列に負のスライスを適用すると（配列の末尾からの要素を示す）、古いバージョンではそのスライスから 1 つのアイテムのみが誤って返されていました。新しいバージョンでは、指定された負の範囲内のすべての要素を含むリスト（配列）が正しく返されるようになりました。

    たとえば、$.store.book[-2:] です。

    以前の動作: 
    {"price":12.99,"category":"fiction","author":"Evelyn Waugh"}
    現在の動作: 
    [
  {"category":"fiction","author":"Evelyn Waugh","price":12.99},
  {"category":"fiction","author":"Herman Melville","price":8.99}
]
    アクション:

    ダウンストリーム処理ロジックを更新して、返された JSON 配列を反復処理し、目的の出力を取得する必要があります。

  6. JSONPath のドットの先行を厳密にチェック

    ルートから直接アクセスされる要素の構文が厳格に適用されます。要素が先頭のドットなしでルートから直接アクセスされる場合（例: $propertyelement）、このような構文はエラーとみなされ、プロキシのデプロイが阻止されます。

    たとえば、$store、

    {
  "bicycle": {
    "color": "red",
    "book": [{"author": "Abc"}]
  },
  "book": [
    {"price": 8.95, "category": "reference", "author": "Nigel Rees"},
    {"price": 12.99, "category": "fiction", "author": "Evelyn Waugh"},
    {"price": 8.99, "category": "fiction", "author": "Herman Melville"}
  ]
}

    現在の動作:

    Proxy will fail to deploy.

    アクション:

    JSONPath を変更してドットを含めます（$.propertyName（例: $.store））。これにより、値が正しくターゲット設定され、取得されます。

  7. 動的 JSONPath 式

    JSONPath 式自体が変数（{myJsonPathVariable} や {dynamicPath} など）で指定されているポリシーには特に注意してください。これらの変数の値も、上記の潜在的な動作の変更と照らし合わせて確認する必要があります。

緩和策

軽減するには、包括的な戦略が必要です。このプロセスでは、適切な更新パスを決定し、JSONPath 式を壊すために必要な修正を適用します。

最適なアップグレード パス方法を選択します。

  • ダウンタイムなしでの移行

    この戦略では、1 つ以上の新しい環境を調達して、個別のメッセージ プロセッサ ノードを接続します。このようなメッセージ プロセッサ ノードは、4.53.01 をインストールするように設定し、最新の JSONPath 式を含むプロキシを使用できます。これらはアップグレード中に使用でき、アップグレードの完了後に廃止できます。この戦略はシームレスですが、スムーズなアップグレードをサポートするために、追加のメッセージ プロセッサ ノードを一時的に調達する必要があります。下記参照:

    • 新しい環境を作成し、バージョン 4.53.01 の新しいメッセージ プロセッサ ノードをこの新しい環境に追加します。
    • 影響を受けるプロキシのプロキシ バンドルを新しい環境にアップロードし、修復セクションで説明されている必要な修正を適用して、更新されたプロキシ バンドルを新しい環境にデプロイします。
    • トラフィックを新しい環境にリダイレクトし、影響を受けたプロキシを古い環境からデプロイ解除します。
    • 元の Message Processor ノードを 4.53.01 にアップグレードします。元の環境で JSONPath の修正を含むプロキシをデプロイします。
    • トラフィックを古い環境に戻します。この環境には、4.53.01 の Message Processor と、新しい jsonpath 式用に最新化されたプロキシがあります。
    • 新しい環境と関連するノードを削除して廃止します。
  • ダウンタイムとアップグレード

    この戦略では、誤った JSON パス式を使用している API プロキシのダウンタイムを確保します。追加のメッセージ プロセッサ ノードの調達は必要ありませんが、影響を受けるプロキシの API トラフィックが中断されます。

    • 影響を受けるポリシーを含む影響を受けるプロキシを特定し、影響を受けるすべてのプロキシの新しいリビジョンを生成します。
    • プロキシの新しいリビジョンで、修復セクションで説明されている修正を実装して、必要な修正を適用します。まだデプロイしないでください。
    • 影響を受けるプロキシのダウンタイムを確保します。
    • すべてのメッセージ プロセッサを Edge for Private Cloud バージョン 4.53.01 にアップグレードします。既存のプロキシは、新しくアップグレードされたメッセージ プロセッサで失敗する可能性があります。
    • すべてのメッセージ プロセッサが Edge for Private Cloud バージョン 4.53.01 にアップグレードされたら、修正された JSONPath 式を使用して、新しく作成されたプロキシ リビジョンをデプロイします。
    • このようなプロキシでトラフィックを再開します。
  • アップグレード前にプロキシを再設計

    Edge for Private Cloud 4.53.01 にアップグレードする前に、プロキシ自体を再設計できます。特定の JSONPath 式に依存する代わりに、別の方法で同じ結果を取得できます。

    たとえば、JSON パスで Extract Variable ポリシーを使用している場合は、新しいバージョンにアップグレードする前に、同様のデータを抽出する Javascript ポリシーに置き換えることができます。アップグレードが完了したら、プロキシを新しい形式の JSON パスを使用するように変更できます。

JavaCallout の変更

コンテキスト

Edge for Private Cloud 4.53.00 以前には、多数の JAR ライブラリを含む deprecated（$APIGEE_ROOT/edge-message-processor/lib/deprecated）というディレクトリが含まれていました。これらのライブラリは JavaCallout ポリシーの Java コードで使用でき、カスタム Java コードで直接または間接的に使用される可能性があります。

変更点

Edge for Private Cloud バージョン 4.53.01 で、非推奨のディレクトリが削除されました。Java コードがこのようなライブラリに依存している場合、メッセージ プロセッサがバージョン 4.53.01 にアップグレードされると、このような Java コールアウトを使用するプロキシは失敗します。このような障害を回避するには、メッセージ プロセッサをバージョン 4.53.01 にアップグレードする前に、次の軽減策の手順を実施してください。

緩和策

  1. Java-Callout ポリシーと関連する JAR を確認し、現在のメッセージ プロセッサの「deprecated」ディレクトリにあるライブラリを参照または使用しているものがあるかどうかを特定します。Java Callout は、組織レベルまたは環境レベルのリソースとしてアップロードされた JAR を使用している場合があります。これらのライブラリも検討してください。
  2. 非推奨のライブラリを特定したら、次のいずれかの方法で問題を軽減できます。
    • リソースの配置（非推奨のディレクトリにある jar / ライブラリの数が少なく、Java-Callout jar によって参照されている場合に推奨）
      • 特定された非推奨の JAR を、目的のレベル（API プロキシ リビジョン、環境、組織）でリソースとしてアップロードします。
      • 通常どおり Apigee ソフトウェアのアップグレードに進みます。
    • 手動配置（Java-Callout jar によって参照される jar / ライブラリが多数ある場合におすすめ）
      • 各メッセージ プロセッサ ノードで、パス $APIGEE_ROOT/data/edge-message-processor/ に external-lib という名前の新しいディレクトリを作成します。
      • 特定された JAR を非推奨のディレクトリ cp $APIGEE_ROOT/edge-message-processor/lib/deprecated/some.jar $APIGEE_ROOT/data/edge-message-processor/external-lib/some.jar からこの external-lib ディレクトリにコピーします。
      • ディレクトリと基盤となる JAR を Apigee ユーザーが読み取れるようにします。chown -R apigee:apigee $APIGEE_ROOT/data/edge-message-processor/external-lib
      • 通常どおり Apigee ソフトウェアのアップグレードに進みます。

OpenLDAP の変更

コンテキスト

OpenLDAP は、Edge Private Cloud で認証と認可の両方に使用できます。Edge for Private Cloud 4.53.01 では、Apigee が提供する OpenLDAP ソフトウェアがバージョン 2.4 から 2.6 にアップグレードされました。

変更点

OpenLDAP 2.6 では、相対識別名（RDN）は約 241 バイト/文字に制限されています。この制限は強制的な上限であり、変更できません。

影響
  • RDN が大きすぎるエントリで、レプリケーションまたはインポートの失敗が発生します。
  • 組織、環境、カスタムロール、権限などのエンティティを作成しようとすると、"message": "[LDAP: error code 80 - Other]" というエラー メッセージが表示されることがあります。
  • Apigee の LDAP で 241 バイトを超える DN は影響を受けます。このような DN が存在すると、Apigee OpenLDAP ソフトウェアのアップグレードが正常に完了しません。アップグレードを続行するには、このような項目に対する緩和策を講じる必要があります。

一般的に、Apigee の LDAP では、長い DN は権限に関連しています。これは、複数のエンティティを連結して作成されるためです。このような権限エントリは、アップグレードの問題が発生しやすくなります。

たとえば、

dn: cn=@@@environments@@@*@@@applications@@@*@@@revisions@@@*@@@debugsessions,ou=resources,cn=businessuser,ou=userroles,o=orgname,ou=organizations,dc=apigee,dc=com

通常、LDAP の RDN が 241 バイト未満になるように、組織名、環境名、ロール名の長さを設定します。

緩和策

4.53.01 にアップグレードする前:

次の手順では、既存の LDAP 2.4 クラスタに長い RDN が存在するかどうかを確認します。

#1 - LDAP データを抽出する

ldapsearch コマンドを使用して識別名（dn）を検索し、出力をファイルにリダイレクトします。

ldapsearch -o ldif-wrap=no -b "dc=apigee,dc=com" -D "cn=manager,dc=apigee,dc=com" -H ldap://:10389 -LLL -x -w LDAP_PASSWORD dn > /tmp/DN.ldif

上記の DN.ldif ファイルに LDAP エントリがあることを確認します。

#2 - 長い RDN を特定する

上記の DN.ldif ファイルから、241 バイト/文字を超える RDN を見つけます。

cat /tmp/DN.ldif |  grep '^dn:' | gawk -F',|dn: ' '{ rdn = $2; char_count = length(rdn); cmd = "echo -n \"" rdn "\" | wc -c"; cmd | getline byte_count; close(cmd); if (char_count > 241 || byte_count > 241) { print rdn, "(chars: " char_count ") (bytes: " byte_count ")"; }}'
o=VeryLongOrgNameWithMoreThan241Chars.... (chars: 245) (bytes: 245)
cn=VeryLongCustomRoleNameWithMoreThan241Chars.... (chars: 258) (bytes: 258)

上記のコマンドで出力が生成されない場合、既存の LDAP 設定の RDN は 241 バイト/文字を超えていません。通常どおりアップグレードを続行しても問題ありません。

上記のコマンドで出力が生成された場合は、241 バイト/文字を超える RDN が存在することを示します。このような項目については、Edge for Private Cloud 4.53.01 のアップグレードに進む前に、ステップ 3 で説明されている緩和策の手順に沿って対応してください。

#3 - 長い RDN を処理

ステップ 2 で出力が返された場合は、241 バイト/文字を超える RDN が存在することを示します。次の軽減策の手順に沿って対応してください。

241 バイトを超える LDAP エントリを確認します。

  • カスタムロール名、アプリ、API プロダクトなどのエンティティが RDN が長くなる主な原因である場合は、名前が短い別のエンティティを使用するように移行します。
  • 長い RDN の主な原因が組織名または環境名である場合は、名前の短い別の組織または環境に移行する必要があります。

LDAP に 241 バイトを超える RDN がなくなるまで、上記の手順を繰り返します。この状態になったら、通常どおりプライベート クラウドのバージョン アップグレードに進みます。

暗号化プロバイダの変更

コンテキスト

この変更は、Edge for Private Cloud 4.53.00 から引き継がれたものです。Edge for Private Cloud 4.53.00 では、FIPS サポートを有効にするために、内部暗号プロバイダが Bouncy Castle（BC）から Bouncy Castle FIPS（BCFIPS）に更新されました。

変更点

JavaCallout ポリシーが元の BC プロバイダの使用に依存している場合（特に、BCFIPS プロバイダで強化されたセキュリティ機能を使用している場合（暗号化と署名に共通の鍵ペアを使用するなど））、そのような JavaCallout ポリシーは最新化する必要があります。名前 BC を使用して Bouncy Castle 暗号プロバイダを読み込もうとする JavaCallout ポリシーは、デフォルトのプロバイダが変更されたため失敗する可能性があります。BC プロバイダを使用するこのようなポリシーは、後で破損する可能性があります。古い BC プロバイダに依存するカスタム実装はアクセスできなくなるため、見直して再実装する必要があります。

緩和策

推奨される回避策は、BCFIPS プロバイダを使用することです。古いプロバイダに依存していたカスタム JavaCallout 実装は、文字列「BCFIPS」を使用してアクセスできる Bouncy Castle FIPS プロバイダを使用して見直し、再実装する必要があります。

自動変更検出ツール

変更検出ツールはまもなくリリースされる予定です。このツールは、この記事で説明するさまざまな変更の影響を受ける可能性のある API プロキシ、共有フロー、リソース、LDAP RDN をスキャンして特定する機能を備えています。このツールは、Edge for Private Cloud 4.53.01 へのアップグレード中またはアップグレード後に障害が発生しやすいさまざまなエンティティの特定に役立ちます。