Edge for Private Cloud 4.53.01 的變更

異動總覽

Edge for Private Cloud 4.53.01 導入多項變更，可提升平台安全狀態，並整合軟體/程式庫的更新版本。這些變更會影響：

  • OAS (OpenAPI 規格) 驗證政策
  • 支援 JSONPath 查詢的政策
  • 使用已淘汰程式庫的 Java 呼叫政策
  • OpenLDAP

本節說明 4.53.01 版導入的各種變更，這些變更可能會在升級期間或升級後中斷工作流程。此外，我們也會介紹如何找出潛在問題區域，以及如何採取緩解或變通方法。

OAS (OpenAPI 規格) 驗證政策

背景資訊

OAS 驗證政策會根據 OpenAPI 3.0 規格 (JSON 或 YAML) 中定義的規則，驗證傳入的要求或回應。Private Cloud 專用 Edge 4.53.01 強化了 OAS (OpenAPI 規格) 政策，著重於更嚴格且更準確地驗證 API 回應內容。

異動

Edge for Private Cloud 4.53.01 版對 OAS 政策驗證 API 回應的方式進行兩項重大變更，確保與 OpenAPI 規格更緊密地保持一致：

  • 情境 1：
    • 先前行為：如果 OpenAPI 規格需要回應主體，但目標或上游政策的實際回應未包含回應主體，政策不會將此標示為驗證錯誤。
    • 目前行為：現在政策會正確傳回驗證錯誤 (例如：defines a response schema but no response body found)，指出預期回應與實際回應不符。
  • 情境 2：
    • 先前行為：如果 OpenAPI 規格明確指出不應有回應主體，但目標或上游政策的實際回應包含主體，政策不會導致失敗。
    • 目前行為：在這種情況下，政策現在會導致失敗 (例如 No response body is expected but one was found)，確保回覆內容嚴格遵守指定的結構定義。

緩解措施

找出任何代理項目或共用流程，其中 OAS 驗證政策已設定 Source 標記為 response，或驗證任何其他會產生回應的政策所傳回的回應。

找出 Proxy/共用流程後，請確保回應與 OAS 規格一致。回覆內容必須嚴格遵守 OpenAPI 規格，說明是否有回覆主體。您可以使用標準 Apigee 追蹤功能查看流量模式。如果目標間歇性傳回回應，請先使用其他政策驗證，再使用 OAS 政策

  • 如果 OAS 規格檔案定義了回應主體，目標或上游政策的回應就必須提供回應主體。
  • 如果 OAS 規格檔案未定義回應本文，目標或上游政策就不得傳送回應本文。

請視需要更新 OAS 驗證政策或目標行為，再嘗試升級至 Private Cloud 4.53.01。您應先在非正式環境中驗證這類工作流程，盡量避免在升級正式叢集時發生中斷。

JSON 路徑

背景資訊

Private Cloud 4.53.01 版的 Edge 變更了各種政策中 JSON 路徑運算式的用法。您可以在政策 (例如「ExtractVariable」政策、「RegularExpressionProtection」政策、「資料遮蓋」政策) 中使用 JSONPath 運算式，剖析 JSON 內容或將值儲存在變數中。您也可以在一般訊息範本中使用 JSONPath 運算式，在 Proxy 執行期間動態將變數替換為值。新版 JSONPath 運算式和格式符合最新 JSON 運算式標準。

異動

請務必檢查現有的 API Proxy/共用流程，找出使用 JSONPath 運算式的政策。包括但不限於「擷取變數」政策、「正規運算式保護」政策，或任何使用 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[*] 會傳回包裝在單一 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 遞迴下降 (..) 輸出結構變更

    使用 (..) (遞迴下降) 運算子找出具名元素的所有出現位置時，傳回結果的方式有所變更。先前，系統會將所有找到的元素扁平化為單一清單。更新後的程式庫現在會傳回清單清單，保留找到元素的原始分組結構，而非單一扁平清單。

    例如：$..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:]) 的行為。先前對陣列套用負數切片 (表示陣列結尾的元素) 時，舊版會錯誤地只從該切片傳回單一項目。新版本現在會正確傳回清單 (陣列)，其中包含指定負數範圍內的所有元素。

    例如 $.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)，系統現在會將這類語法視為錯誤，並禁止部署 Proxy。

    例如 $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 運算式套用必要修正。

選擇最適合您的升級路徑方法：

  • 零停機時間遷移

    這項策略需要採購一或多個新環境，以便將個別訊息處理器節點連接至該環境。這類訊息處理器節點可以設為安裝 4.53.01，並使用含有新式 JSONPath 運算式的 Proxy。這些項目可在升級期間使用，升級完成後即可停用。這項策略可順利升級，但需要暫時採購額外的訊息處理器節點，才能支援順暢升級。詳情如下：

    • 建立新環境，並將 4.53.01 版的新訊息處理器節點新增至這個新環境。
    • 將受影響 Proxy 的 Proxy 套件上傳至新環境，並套用補救措施一節中說明的必要修正，然後將更新後的 Proxy 套件部署至新環境。
    • 將流量重新導向新環境，並從舊環境取消部署受影響的 Proxy。
    • 將原始訊息處理器節點升級至 4.53.01 版。在原始環境中部署已修正 JSONPath 的 Proxy。
    • 將流量切換回舊環境，現在舊環境的訊息處理器為 4.53.01 版，且已更新 Proxy，可支援新的 JSONPath 運算式。
    • 刪除並停用新環境和相關聯的節點。
  • 停機時間和升級

    這項策略會使用有誤的 JSON 路徑運算式，導致 API Proxy 停機。這不會導致需要採購額外的訊息處理器節點，但會中斷受影響 Proxy 的 API 流量。

    • 找出受影響的 Proxy 和政策，並為所有受影響的 Proxy 產生新修訂版本。
    • 在新的 Proxy 修訂版本中，實作補救措施一節中說明的修正方式，套用必要的修正方式。請勿立即部署。
    • 為受影響的 Proxy 安排停機時間。
    • 將所有訊息處理器升級至 Edge for Private Cloud 4.53.01 版。請注意，升級後的訊息處理器可能會導致現有 Proxy 失敗。
    • 所有訊息處理器升級至 Edge for Private Cloud 4.53.01 版後，請部署新建立的 Proxy 修訂版本，其中包含修正後的 JSONPath 運算式。
    • 繼續透過這類 Proxy 傳輸流量。
  • 先重新設計 Proxy 再升級

    您可以先重新設計 Proxy，再升級至 Edge for Private Cloud 4.53.01。您可以使用其他方法，取得與特定 JSON 路徑運算式相同的結果。

    舉例來說，如果您使用含有 JSON 路徑的「擷取變數」政策，可以先將該政策換成擷取類似資料的 JavaScript 政策，再升級至新版。升級完成後，您可以將 Proxy 變更回使用 JSON 路徑和較新格式。

JavaCallout 變更

背景資訊

Edge for Private Cloud 4.53.00 版和更早版本包含名為 deprecated ($APIGEE_ROOT/edge-message-processor/lib/deprecated) 的目錄，其中包含許多 JAR 程式庫。這些程式庫可在 JavaCallout 政策的 Java 程式碼中使用，且可直接或間接由自訂 Java 程式碼使用。

異動

在 Edge for Private Cloud 4.53.01 版中，系統已移除已淘汰的目錄。如果您的 Java 程式碼依賴這類程式庫，當訊息處理工具升級至 4.53.01 版時，使用這類 Java 呼叫的 Proxy 將會失敗。為避免發生這類失敗情形，請先按照下列緩解步驟操作，再將訊息處理器升級至 4.53.01 版。

緩解措施

  1. 請檢查 Java-Callout 政策和相關聯的 JAR，找出是否有任何政策或 JAR 參照或使用目前訊息處理工具「已淘汰」目錄中的程式庫。請注意，Java 呼叫可能會使用以機構或環境層級資源上傳的 JAR。也請考慮使用這些程式庫。
  2. 找出這類已淘汰的程式庫後，您可以按照下列其中一種方法解決問題。
    • 資源放置位置 (如果 Java Callout JAR 參照的已淘汰目錄中只有少量 JAR / 程式庫，建議使用這個選項)
      • 在所需層級 (API Proxy 修訂版本、環境或機構) 上傳已識別的已淘汰 JAR 做為資源。
      • 照常進行 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
      • 確認 Apigee 使用者可讀取目錄和基礎 JAR：chown -R apigee:apigee $APIGEE_ROOT/data/edge-message-processor/external-lib
      • 照常進行 Apigee 軟體升級。

OpenLDAP 變更

背景資訊

在 Edge Private Cloud 中，OpenLDAP 可用於驗證和授權。在 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 是由串連多個實體所建立。這類權限項目特別容易發生升級問題。

舉例來說，

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

一般而言，您會將機構、環境和角色名稱的長度設為小於 241 個位元組，以確保 LDAP 中的 RDN 也是如此。

緩解措施

升級至 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 - Identify long RDNs

從上述 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 個位元組/字元。您可以照常升級。

如果上述指令產生輸出內容，表示 RDN 超過 241 個位元組/字元。如要升級 Edge for Private Cloud 4.53.01，請先按照步驟 3 所述的緩解步驟操作。

#3 - Handle long RDNs

如果收到步驟 2 的輸出內容，表示 RDN 超過 241 個位元組/字元，請按照下列緩解步驟操作：

查看超過 241 個位元組的 LDAP 項目。

  • 如果是自訂角色名稱、應用程式、API 產品或其他實體導致 RDN 過長，請改用名稱較短的替代實體。
  • 如果組織名稱或環境名稱是造成 RDN 過長的主要原因，您就必須遷移至名稱較短的其他組織或環境。

請重複上述步驟，直到 LDAP 中沒有長度超過 241 個位元組的 RDN 為止。達到這個狀態後，請照常升級私有雲版本。

密碼編譯提供者變更

背景資訊

這項變更沿用自 Edge for Private Cloud 4.53.00。在 Edge for Private Cloud 4.53.00 中，內部密碼編譯供應商已從 Bouncy Castle (BC) 更新為 Bouncy Castle FIPS (BCFIPS)，以啟用 FIPS 支援。

異動

如果 JavaCallout 政策依賴使用原始 BC 提供者，特別是使用 BCFIPS 提供者中經過強化的安全性功能 (例如，同時使用常見的金鑰組進行加密和簽署)，則這類 JavaCallout 政策需要進行現代化。嘗試使用名稱 BC 載入 Bouncy Castle 密碼編譯供應商的 JavaCallout 政策可能會失敗，因為預設供應商已變更。使用 BC 提供者的這類政策隨後可能會中斷。凡是依賴舊版 BC 提供者的自訂實作項目，都將無法再存取，必須經過審查並重新實作。

緩解措施

建議的解決方法是使用 BCFIPS 提供者。如果自訂 JavaCallout 實作項目依賴舊版供應商，則必須使用 Bouncy Castle FIPS 供應商重新實作，並透過「BCFIPS」字串存取。

自動變更偵測工具

我們預計近期推出變更偵測工具。這項工具可掃描並找出可能受到本文所述各種異動影響的 API Proxy、共用流程、資源和 LDAP RDN。這項工具可協助您找出在升級至 Edge for Private Cloud 4.53.01 期間或之後，容易發生故障的各種實體。