Edge for Private Cloud 4.53.01 の変更点

変更の概要

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

変更検出ツールを使用して、このアップグレードの結果として中断を引き起こす可能性があるクラスタ内のプロキシ、共有フロー、その他のアーティファクトの変更を特定することもできます。

変更の詳細な説明

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

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

コンテキスト

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

変更点

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）が発生し、レスポンスが指定されたスキーマに厳密に準拠するようになります。

緩和策

変更検出ツールを使用するか、手動で確認して、アップグレードの影響を受ける可能性のあるプロキシまたは共有フローを特定します。次のいずれかの条件に該当するプロキシを探します。

  • OAS 検証ポリシーは、response に設定された Source タグで構成されています。
  • OAS Validation ポリシーは、レスポンスを生成する他のポリシーからのレスポンスを検証しています。

ツールを使用すると、次の形式で出力が生成されます。

組織 環境 アーティファクト名 アーティファクト タイプ リビジョン ポリシー名 ポリシーの種類 影響の種類 Impact Specific Field 影響の確実性 ドキュメント
org2 dev proxy2 proxy 4 oas-validateresponse OASValidation oas_content_type_handling Source=calloutresponse 中 OAS 検証ポリシー
org1 prod proxy3 sharedflow 1 oas-spec-validation OASValidation oas_content_type_handling Source=response 中 OAS 検証ポリシー

出力テーブルの列の詳細については、ツールの出力を理解するセクションをご覧ください。

プロキシまたは共有フローが特定されたら、レスポンスの本文の有無に関して、レスポンスと OAS 仕様が一致していることを確認します。標準の 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"}
    現在の動作: 
    []
    アクション:

    フィルタリングしてから、フィルタリングされたセットから特定のアイテムを取得する必要がある場合は、たとえば $..book[?(@.category == 'fiction')] の JSONPath によって返されたフィルタリングされた配列を処理し、前の結果から [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} など）で指定されているポリシーには特に注意してください。これらの変数の値も、上記の潜在的な動作の変更と照らし合わせて確認する必要があります。

緩和策

変更検出ツールを使用するか、API プロキシを手動で確認して、説明したパターンを探すことで、アップグレードの影響を受ける可能性のあるプロキシまたは共有フローを特定します。このツールを使用すると、影響を受けるプロキシまたは共有フロー、関連するポリシー、問題のある JSON パスが特定されます。次の出力例をご覧ください。

組織 環境 アーティファクト名 アーティファクト タイプ リビジョン ポリシー名 ポリシーの種類 影響の種類 Impact Specific Field 影響の確実性 ドキュメント
org1 dev proxy1 proxy 4 EV-ExtractRequestParams ExtractVariables オブジェクト値の JSONPath ワイルドカード [*] の動作変更 $.store[*] 高 オブジェクト値の JSONPath ワイルドカード [*] の動作変更
org2 prod proxy2 sharedflow 1 EV-ExtractResponseParams ExtractVariables パスの末尾のドット（.）が原因でエラーが発生する $.store.book. 高 パスの JSONPath の末尾のドット（.）が原因でエラーが発生する
org3 dev proxy3 proxy 3 SC-FetchUserProfile ServiceCallout JSONPath 再帰下降（..）の出力構造の変更 $..book 高 JSONPath 再帰下降（..）の出力構造の変更
org4 prod proxy4 sharedflow 2 RF-InvalidAuthToken RaiseFault 複数アイテムの選択またはフィルタ後の JSONPath インデックスが空の配列を返すようになりました $.store.book[*][0] 高 複数項目の選択またはフィルタ後の JSONPath インデックス作成で空の配列が返される
org5 テスト proxy5 proxy 6 SC-FetchProfileDetails ServiceCallout JSONPath の負の配列スライシングの出力の変更 $.store.book[-2:] 高 JSONPath の負の配列スライシングの出力の変更
org6 prod proxy6 proxy 2 ML-LogRequestDetails MessageLogging JSONPath の厳密な先行ドット $store 高 JSONPath の厳密な先行ドット
org7 テスト proxy7 proxy 5 RF-InvalidTokenDetails RaiseFault 動的 JSONPath 式 myJsonPathVariable 中 動的 JSONPath 式

上記の出力テーブルの列の詳細については、ツールの出力を理解するセクションをご覧ください。

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

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

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

    この戦略では、1 つ以上の新しい環境を調達して、個別のメッセージ プロセッサ ノードを接続します。このような Message Processor ノードは、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」ディレクトリにあるライブラリを参照しているポリシーがないか確認します。

    上記検出に Apigee が提供するツールを使用している場合、ツールは次の表に示すレポートを生成します。具体的には、古い Edge for Private Cloud バージョンの $APIGEE_ROOT/edge-message-processor/lib/deprecated ディレクトリにある JAR を参照するポリシーを対象としています。

    ツールは、次の形式でレポートを生成します。

    組織 環境 アーティファクト名 アーティファクト タイプ リビジョン ポリシー名 ポリシーの種類 影響の種類 Impact Specific Field 影響の確実性 ドキュメント
    org1 なし なし org-level-jar なし なし java-callout simple-javacallout-o1-jar-1.jar で非推奨ライブラリが検出されました ['Detected use of class org.apache.commons.io.FileUtils from commons-io-2.5.jar, 'Detected use of class org.apache.commons.io.input.XmlStreamReaderException from commons-io-2.5.jar'] 高 JavaCallout の変更
    org3 env3 なし env-level-jar なし なし java-callout fat-javacallout-e3-jar-1.jar で非推奨ライブラリが検出されました ['Detected use of class org.apache.http.impl.auth.NTLMSchemeFactory from httpclient-4.5.2.jar'] 高 JavaCallout の変更
    org1 env1 p1 proxy-level-jar 1 なし java-callout simple-javacallout-p1-jar-1.jar で非推奨ライブラリが検出されました ['Detected use of class org.apache.commons.lang3.builder.ToStringBuilder from commons-lang3-3.4.jar', 'Detected use of class org.apache.commons.lang3.Validate from commons-lang3-3.4.jar'] 高 JavaCallout の変更

    上記の出力テーブルの列の詳細については、ツールの出力を理解するセクションをご覧ください。

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

変更検出ツールは、生成された LDIF ファイルを使用して、241 バイト/文字を超える LDAP RDN を特定します。

ツールは、次の形式でレポートを生成します。

組織 環境 アーティファクト名 アーティファクト タイプ リビジョン ポリシー名 ポリシーの種類 影響の種類 Impact Specific Field 影響の確実性 ドキュメント
なし なし cn=really-long-name,ou=userroles,o=edge-platform,ou=organizations,dc=apigee,dc=com ldif ファイル なし なし なし Ldap RDN が 241 文字を超えている cn=really-long-name 高 OpenLDAP の変更

上記の出力テーブルの列の詳細については、ツールの出力を理解するセクションをご覧ください。

上記のコマンドで出力が生成されない場合、既存の 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 プロバイダを使用して見直し、再実装する必要があります。

変更検出ツール

Edge for Private Cloud 4.53.01 への移行中および移行後に影響を受ける可能性のある Apigee プロキシ、ポリシー、共有フローを特定するために、変更検出ツールが構築されています。このツールは、変更の影響を受けるデプロイされたプロキシ、共有フロー、OpenLDAP の詳細を記載したレポートを生成し、特定されたプロキシまたは共有フローに関連する特定のガイドと戦略への指示を提供します。

前提条件

  1. このツールを実行するには、RHEL ベースのマシンが必要です。
  2. ツールのスクリプトを実行できるように、JRE 8 をホスト仮想マシンにインストールして正しく構成する必要があります。
  3. このツールでは、認証とデータ取得のために、Management Server の正しいエンドポイント（URL）と有効な管理者認証情報が必要です。
  4. このツールでは、バンドルの抽出、ログの生成、出力の保存を行うために、指定された作業ディレクトリ（/tmp など）へのアクセスが必要です。このディレクトリに十分なディスク容量があり、適切な読み取り/書き込み権限があることを確認します。
  5. このツールでは、OpenLDAP の変更 - LDAP データの抽出セクションの ldapsearch コマンドを使用して LDIF ファイルを取得し、241 文字 / バイトを超える長い RDN を検出する必要があります。

ツールの実行

上記の前提条件をすべて満たしたら、Apigee リポジトリへのアクセスに使用する Apigee のユーザー名とパスワードを指定して、ツールをダウンロードします。ダウンロードが完了したら、ダウンロードしたアーカイブを抽出します。

curl -u uName:pWord https://software.apigee.com/apigee/change-detector/change-detector-for-4.53.01_1.0.0.zip -o /tmp/change-detector-for-4.53.01_1.0.0.zip
 
unzip /tmp/change-detector-for-4.53.01_1.0.0.zip

ダウンロードが完了したら、次のコマンドを実行して、ツールの使用可能なすべてのオプションを確認できます。

./change-detector --help

ツールを実行するには、次のコマンドを使用し、プレースホルダを実際の情報に置き換えます。

export APIGEE_PASSWORD=[your_password]
./change-detector --username [your_username] --mgmt-url [MGMT url]

大きな RDN LDAP エントリを検出するには、次のコマンドを実行します。

./change-detector --username [your_username] --mgmt-url [MGMT url] --ldif-file [LDIF_file]

このツールは、直接使用できるか、Google スプレッドシートなどの人間が読めるツールにインポートできる JSON または CSV 形式で出力を生成します。

ツールの出力を理解する

組織

アーティファクトが配置されている組織の名前を指します。OpenLDAP の変更の場合、これは None になります。

環境

組織内の特定の環境（開発、テスト、本番環境など）。OpenLDAP の変更の場合、これは None になります。

Java Callout の変更の場合、Artifact Type=env-level-jar の場合、このフィールドは None になります。

アーティファクト名

このフィールドは、プロキシ/共有フローの名前を示します。OpenLDAP の変更の場合、このフィールドには RDN の LDAP エンティティが表示されます。

Java コールアウトの変更の場合、Artifact Type=env-level-jar または org-level-jar の場合、このフィールドは None になります。

アーティファクト タイプ

  • OAS と JSON の変更の場合、この列はアーティファクト、プロキシ、共有フローのタイプを指定します。
  • Java Callout の変更の場合、この列には、影響を受ける jar がアップロードされる場所またはレベルに関する詳細が示されます。リソース（JAR）は、org-level、env-level、proxy-level の 3 つのレベルのいずれかに保存できます。
  • OpenLDAP の変更の場合、このフィールドはツールで使用される LDIF ファイルを示します。

リビジョン

影響を受けるプロキシ/共有フローのデプロイされたリビジョンを指します。OpenLDAP の変更の場合は None になります。

ポリシー名

潜在的な問題として特定された特定のポリシーの名前。OpenLDAP の変更の場合は None になります。

ポリシータイプ

ポリシーのタイプを指します。OpenLDAP の変更の場合は None になります。

影響の種類

  • このフィールドは、プロキシ/共有フローで検出された変更の具体的なタイプを示します。
  • Java Callout の変更の場合、java-callout に関連する変更の検出では、この特定の列で、以前のバージョンの Edge for Private Cloud の $APIGEE_ROOT/edge-message-processor/lib/deprecated ディレクトリにある JAR を参照している影響を受ける java-callout が次のように示されます。
    • deprecated library detected for NAME_OF_THE_AFFECTED_JAVA_CALLOUT_JAR
  • OpenLDAP の変更の場合、このフィールドには、LDAP エンティティの RDN が 241 バイトまたは文字を超えたかどうかが表示されます。

Impact specific field（影響の具体的なフィールド）

  • OAS の変更の場合、このフィールドはポリシーの Source タグで使用される変数の名前です。
  • JSON の変更の場合、このフィールドには、潜在的な問題としてフラグが設定された正確な JSONPath 式または要素が表示されます。
  • Java Callout の変更の場合、このフィールドには、影響を受ける JavaCallout jar で使用または参照される正確なクラスの詳細と、対応する JAR の名前（以前の Private Cloud バージョンの $APIGEE_ROOT/edge-message-processor/lib/deprecated ディレクトリに存在）が含まれます。この JAR は、緩和策が適用されていない場合、バージョン 4.53.01 にアップグレードするとエラーが発生します。
    •  ['Detected use of class CLASS_NAME_1 from JAR_NAME_1',
    Detected use of class CLASS_NAME_2 from JAR_NAME_2', 
  .. , .. , ]
  • OpenLDAP の変更の場合、このフィールドには、241 バイトまたは文字を超えた LDAP エンティティの RDN がすべて表示されます。

影響の確実性

  • このフィールドは、ツールが特定のアイテムを検出した確実性の程度を示します。この列の値は、高または中のいずれかになります（後で値が追加される可能性があります）。

    値が「高」の場合、バージョン 4.53.01 にアップグレードした後に、そのアイテムが原因でアプリが破損する可能性が非常に高いとツールが判断したことを意味します。Medium 値は、ツールが検出について不明確であり、判断を下すにはより多くの戦略が必要であることを示します（たとえば、プロキシ実行中に解決された変数を観察するためにトレースをキャプチャします）。

  • JavaCallout と OpenLDAP の変更に関連する検出では、影響の確実性列の値は常に「高」になります。

ドキュメント

この列には、問題とその軽減策について説明する Apigee のドキュメント（この記事の関連セクション）へのハイパーリンクが表示されます。