Apigee 已知問題

自 Apigee hybrid 1.14.0 版起，系統已不再自動新增 Zipkin 追蹤標頭 (x-b3-*)。

不適用

如果您只指定 httpProxy，請務必確認 Apigee Runtime 容器的允許清單中包含 *.googleapis.com，以便啟用這些服務的連線功能。

請參閱「為 API Proxy 設定轉送 Proxy」。

在 Apigee 混合叢集中存在 istio.io 自訂資源定義 (CRD) 時，可能會導致 apigee-ingressgateway-manager 容器發生失敗。

在 Apigee Hybrid 從舊版升級至 1.14.2 的過程中，如果存在現有的 istio.io CRD，可能會導致 apigee-ingressgateway-manager 容器的 discovery 容器無法通過就緒探查。

解決方法：Apigee 不需要 istio.io CRD。刪除或升級叢集中的 istio.io CRD，然後解除安裝並重新安裝 ingress-manager 元件。

1. 將叢集中的 istio.io CRD 列入 CSV 檔案：

   kubectl get crd -o custom-columns=NAME:metadata.name | grep istio.io > istio-crd.csv

2. 選用：如需重新建立 CRD，請在本機儲存 CRD：

   kubectl get crd $(cat istio-crd.csv) -o yaml > istio-crd.yaml

3. 刪除 istio.io CRD：

   模擬測試：

   kubectl delete crd $(cat istio-crd.csv) --dry-run=client

   執行：

   kubectl delete crd $(cat istio-crd.csv)

4. 列出要重新安裝或重建的 ingress-manager Pod：

   kubectl get deployments -n apigee

   輸出內容範例：

   NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
   apigee-controller-manager       1/1     1            1           32d
   apigee-ingressgateway-manager   2/2     2            2           32d
   

5. 重新啟動 ingress-manager 容器：

   kubectl rollout restart deployment -n APIGEE_NAMESPACE apigee-ingressgateway-manager

ApigeeTelemetry 可能會卡在 creating 狀態。

這個問題已在 OpenShift 安裝作業中發生。

解決方法：修改 apigee-operator 圖表範本，建立正確的叢集角色存取權。

1. 編輯 helm-charts/apigee-operator/templates/apigee-operators.yaml 範本檔案，並找出 -apigee-manager-role- 叢集角色的定義。開頭為：

   kind: ClusterRole
   metadata:
     name: apigee-manager-role-{{ include 'namespace' }}
   rules:
     ...
                 

2. 找出 - apiGroups: apiregistration.k8s.io 區塊，並將 apiservices/finalizers 資源新增至資源清單：

   - apiGroups:
     - apiregistration.k8s.io
     resources:
     - apiservices
     - apiservices/finalizers
     verbs:
     - create
     - delete
     - get
     - patch
     - update
     

3. 找出 - apiGroups: authorization.k8s.io 區塊，然後在區塊結尾處加入 - apiGroups: apigee.cloud.google.com 區塊，並加入以下文字：

   - apiGroups:
     - apigee.cloud.google.com
     resources:
     - apigeetelemetries/finalizers
     verbs:
     - get
     - patch
     - update
   

   例如：

   - apiGroups:
     - authorization.k8s.io
     resources:
     - subjectaccessreviews
     verbs:
     - create
     - get
     - list
   - apiGroups:
     - apigee.cloud.google.com
     resources:
     - apigeetelemetries/finalizers
     verbs:
     - get
     - patch
     - update
   

4. 將變更套用至 apigee-operator 圖表：

   模擬測試：

   helm upgrade operator apigee-operator/ \
     --install \
     --namespace APIGEE_NAMESPACE \
     --atomic \
     -f OVERRIDES_FILE \
     --dry-run=server
   

   升級圖表：

   helm upgrade operator apigee-operator/ \
     --install \
     --namespace APIGEE_NAMESPACE \
     --atomic \
     -f OVERRIDES_FILE \
   

API 產品的路徑上限為 50 個。如果您新增其他路徑，系統會顯示錯誤訊息： Operation group limit of 51 exceeded in Operation Config

解決方法：如同「 設定資源路徑」一文所述，使用萬用字元模式結合資源路徑和作業。

解決方法：建立多個 API 產品。這個因應措施已通過驗證，適用於向 API 產品新增大量 API Proxy 的使用者。與 API 產品相關聯的應用程式需要更新，才能納入新的產品，但已證明憑證和用戶端要求詳細資料不需要變更。

針對使用營利功能的安裝項目，依費率類型選取時，使用自訂報表和統計資料 API 會發生錯誤。

解決方法：請先在用戶端擷取所有費用類型，再進行篩選。

擴充 Istio ingress Pod 可能會導致 503 錯誤。

調整 Istio ingress 容器有時可能會導致 503 錯誤。如果發生 503 錯誤，負載平衡器的記錄會顯示以下訊息：statusDetails: backend_connection_closed_before_data_sent_to_client。

解決方法：手動調度 Istio ingress Pod。

ESS 和 非 ESS Cassandra 憑證輪替功能不適用於啟用「強化 Proxy 限制」的機構。

執行階段流量不會受到影響。

使用 GCP 和 HYBRID 雲端服務供應器從多區域設定中擷取的備份，會包含快照擷取時存在的所有混合區域資訊。由於這些區域已不存在，因此還原作業會與 Cassandra 目前狀態發生衝突，並會失敗，並顯示以下錯誤訊息：Unrecognized strategy option passed to NetworkTopologyStrategy。

使用 JavaCallout 政策時，Nimbus JOSE + JWT 程式庫可能會導致 java.lang.ClassCircularityError。

如果您有支援 Apigee 混合式機構，且 JavaCallout 政策使用 Nimbus JOSE + JWT 程式庫，請勿升級至混合式 1.12.4、混合式 1.13.3、混合式 1.14.1 以上版本。

ESS 和 非 ESS 多區域 Cassandra 憑證輪替作業會在所有區域 (除了第一個區域) 失敗。

執行階段流量不會受到影響。

請按照提供的解決方法解決這個問題。

套用 Cassandra 覆寫值變更後，Cassandra 會重新啟動 Pod，例如重新啟用備份時，這會觸發此問題。處於 CrashLoopBackoff 狀態的 Cassandra pod 記錄會顯示以下錯誤：Cannot change the number of tokens from 512 to 256。

請按照提供的解決方法解決這個問題。

在極少數情況下，Apigee 備份工作不會清理使用 HYBRID 或 GCP 雲端服務供應商備份時建立的 Cassandra 中繼快照。只有在發生導致備份程序無法順利連線至遠端伺服器或 Cloud Storage 的潛在問題時，才會發生這種情況。如果連線問題仍未解決，這些剩餘的 Cassandra 快照可能會隨著時間累積，使用 Cassandra 磁碟上的儲存空間。 如果您受到影響，請修正潛在的連線問題，然後按照 Cassandra 疑難排解指南中的步驟，手動清除 Cassandra 快照。

當 KeyValueMapOperations 政策與 apiproxy 範圍搭配使用，且政策的 <Put> 作業透過流程掛鉤在共用流程中呼叫時，KVM 項目會在共用流程名稱下建立。應會在 API Proxy 名稱下方建立。

384937220

當有多個虛擬主機時，Helm 版本建立作業可能會因 ApigeeRoute 名稱衝突而失敗。解決方法是在建立時，針對每個虛擬主機執行下列指令：

kubectl annotate ar apigee-ingressgateway-internal-chaining-PROJECT_ID_SUFFIX -n APIGEE_NAMESPACE meta.helm.sh/release-name=NEW_ENV_GROUP_NAME --overwrite
kubectl annotate cert apigee-ingressgateway-internal-chaining-PROJECT_ID_SUFFIX -n APIGEE_NAMESPACE meta.helm.sh/release-name=NEW_ENV_GROUP_NAME --overwrite

其中：

• PROJECT_ID_SUFFIX 是 Kubernetes 中專屬於專案內部鏈結的後置字串。您可以使用下列指令找出這個後置字串：

  kubectl get svc -n apigee -l app=apigee-ingressgateway | grep internal-chaining

  輸出內容如下所示：

  kubectl get svc -n apigee -l app=apigee-ingressgateway | grep internal-chaining
  apigee-ingressgateway-internal-chaining-my-project--1234567    ClusterIP  34.118.226.140  <none>    15021/TCP,443/TCP    5d6h

  在範例輸出內容中，my-project--1234567 是 PROJECT_ID_SUFFIX。

• APIGEE_NAMESPACE 是 Apigee 命名空間。
• NEW_ENV_GROUP_NAME 是額外環境群組的名稱。為每個虛擬主機更新這個值。

不適用

如果使用者向 UpdateControlPlaneAccess API 提供無效的服務帳戶，作業會進入重試迴圈，有效地鎖定機構，使其無法在作業逾時前叫用 API。

使用 GCP Cloud Provider 時，Apigee 備份工作無法上傳至設有保留政策的 Cloud Storage 值區。備份檔案可能會保留在 Cloud Storage 值區中，且檔案大小為 0 位元組。

解決方法：停用 Cloud Storage 值區的保留政策。

341099433

apigee-logger 會使用 Google IAM 服務帳戶將記錄檔傳送至 Cloud Logging。這是因為 FluentBit 不支援 Workload Identity 聯盟，因此 apigee-logger 無法使用這項功能。

不適用

不適用

270574696

268104619

364872027

針對 Apigee 和 Apigee Hybrid 1.13 以上版本，如果在 Apigee JWS 或 JWT 政策中使用的金鑰與所需 PEM 格式有所出入，可能會導致剖析錯誤。舉例來說，如果在 "-----END" 行 (後封裝邊界) 前方立即放置任何字元 (/n) 以外的字元，系統將不允許，並導致錯誤。

為避免發生這類錯誤，請確認在後封裝邊界之前，除了換行符號之外，沒有任何字元 (例如尾端空格或斜線) 立即前置。

如要進一步瞭解用於公開或私密金鑰的編碼，請參閱 IETF RFC 7468。

310191899

下列端點在每秒查詢次數 (QPS) 較高時，可能會發生逾時情形：

• organizations.environments.apis.revisions.
  deployments.deploy
• organizations.environments.apis.revisions.
  deployments.undeploy
• organizations.environments.sharedflows.revisions.
  deployments.deploy
• organizations.environments.sharedflows.revisions.
  deployments.undeploy

為降低逾時的可能性，建議您在使用這些端點時，將目標設為 1 QPS，或是在嘗試其他部署作業前，先檢查部署作業的狀態。

329304975

Apigee 目前實施了暫時限制，每個環境最多只能有 1000 個 basepath，以免在部署 API Proxy 修訂版本時發生潛在失敗。

在實施這項限制的情況下，您最多可在每個環境中部署 1000 個 API 代理程式修訂版本 (每個版本都包含單一 basepath)。 如果 API 代理程式或修訂版本包含多個 basepath，每個環境的 basepath 總數不得超過 1000 個。

333791378

如要瞭解安裝解決方法修補程式的步驟，請參閱 疑難排解。

310384001

289583112

如果 OASValidation 政策指定的 <OASResource> 安全性需求設為全域層級，則系統不會強制執行安全性需求。

解決方法：為確保執行，所有安全性需求都必須在 OASValidation 政策的 <OASResource> 元素中傳遞的 OpenAPI 規格操作層級中設定。

205666368

請參閱「關於在目標端點或目標伺服器中設定 TLS 選項」。

295929616

在 OSE 上安裝或升級至 Apigee hybrid 1.10.0 至 1.10.2 可能會因記憶體不足而失敗。已在 Apigee Hybrid 1.10.3 版本中修正。

292118812

如果防火牆強制所有流量透過轉送 Proxy，apigee-udca 可能會進入 crash-loop 的 backoff 狀態。

292558790

• 如果 JSON 內容不符合預期的模式，OASValidation 政策就會失敗。舉例來說，如果標頭預期值的格式為 <text>@<text>，但填入的文字缺少 @ 符號，則政策就會失敗，並傳回 Unable to parse JSON 錯誤。
• 如果 OASValidation 政策指定的 <OASResource> 包含使用 $ref 結構定義的 path 參數，政策就會失敗，並顯示 Unable to parse JSON - Unrecognized token 錯誤。

  解決方法：請勿在 <OASResource> 元素中指定的 OpenAPI 規格 path 參數中使用 $ref。

297012500

• 使用 OpenAPI 3.0.0 規範的迴圈參照會進入無限迴圈，因此 Apigee 部署作業會因 OAS 驗證政策而失敗。

解決方法：使用不含循環參照的 OpenAPI 規格 yaml。

289254725

如果 Proxy 部署包含 OASValidation 政策，可能會失敗：

• 在 OASValidation 政策中用於驗證的 OpenAPI 規格為 YAML 格式，
• YAML 格式的 OpenAPI 規格包含浮點數。例如：

  schema:
  type: number
  example: 2.345

284500460

為避免回覆用戶端時的延遲時間增加，請將訊息記錄政策附加至 PostClientFlow。如要進一步瞭解如何在 PostClientFlows 中使用政策，請參閱「 透過流程控制 API 代理程式」。

282997216

Cassandra Jolokia 密碼只能使用英數字元。使用特殊字元 (包括但不限於「!」、「@」、「#」、「$」、「%」、「^」、「&」和「*」) 可能會導致 Cassandra 啟動失敗。

270371160

Apigee Ingress 網關僅支援 TLS 1.2 以上版本，不支援舊版 TLS。

269139342

Apigee 組織驗證未遵循 overrides.yaml 中設定的 HTTP 轉送 Proxy 規則。將 validateOrg: false 設為略過這項驗證。

266452840

在某些情況下，使用 Anthos 服務網格 1.15.3-asm.6 時，Apigee X 和 Apigee Hybrid 的網路通訊端連線無法運作。

242213234

嘗試載入 API 產品時，系統可能會傳回以下錯誤： "Products were not loaded successfully. 錯誤：Apigee Connect 代理程式沒有可用的連線。

在 Google Cloud 專案中啟用 VPC 服務控制功能，並將 iamcredentials.googleapis.com 新增為服務範圍中的受限制服務之一後，就會發生這個問題。

解決方法：手動建立出口規則，例如：

-egressTo:
    operations:
    -serviceName: "iamcredentials.googleapis.com"
        methodSelectors:
        -method:
    resources:
    -projects/608305225983
  egressFrom:
    identityType: ANY_IDENTITY

247540503

在某些情況下，如果吞吐量非常高，則加密金鑰查詢的競爭狀態可能會導致 KVM 查詢失敗。

258699204

如果您發現 apigee-telemetry-app 或 apigee-telemetry-proxy 執行單元無法運作，請變更 metrics 資源要求和資源限制屬性，讓這些屬性與 設定屬性參考資料：指標中的預設值相符。

使用 ‑‑telemetry 標記的 apigeectl apply 套用變更：

apigeectl apply --telemetry -f overrides.yaml

260324159

在某些情況下，由於同步器發生「socket closed」錯誤，API Proxy 和共用流程可能需要 20 到 30 分鐘才能在執行階段平面中部署。

214447386

這項作業預計每分鐘執行一次，且不會影響您的帳單費用。

260772383

如果在 AKS 上安裝 Hybrid，您可能會看到以下錯誤：

envoy config listener '0.0.0.0_443' failed to bind or apply socket options: cannot bind '0.0.0.0:443': Permission denied

解決方法：在覆寫檔案中新增以下 svcAnnotations 段落：

ingressGateways:
- name: INGRESS_NAME
  ...
  svcAnnotations:
    service.beta.kubernetes.io/azure-load-balancer-internal: "true"

請參閱「 設定混合式執行階段」。另請參閱「 在 AKS 中使用內部負載平衡器」。

241786534

使用組織範圍的 UDCA 時，MART 有時無法連線至 FluentD。在 Apigee Hybrid 1.8 版本中，組織範圍的 UDCA 是預設值。請參閱設定屬性參考資料中的 orgScopedUDCA。

在 Apigee hybrid 1.6.6 版中，將 apigee-logger 從 fluend 遷移至 fluent-bit 後，記錄器在使用 CentOS 或 RHEL 的 Anthos BareMetal 上停止運作。

目前的 apigee-logger 設定 (包括有效性探測) 與 Kubernetes 執行階段不相容，導致記錄無法如預期傳送至 Cloud Logging。這個問題也會導致 apigee-logger 容器經常當機。此問題會影響 AKS、Anthos Bare Metal 和其他平台上的 Apigee 混合型安裝作業。請注意，在某些情況下，這個問題會導致記錄檔數量過多。

在 Apigee UI 中，您無法查看、確認部署狀態或管理封存部署作業，如「 部署 API Proxy」一文所述；也無法使用「 使用偵錯功能」一文所述的偵錯 UI。解決方法是使用 gcloud 或 API 列出環境中的所有封存部署作業，然後使用 Debug API。

目前不支援回溯封存的部署作業。 如要移除封存版本的部署作業，您必須 重新部署先前版本的封存資料，或 刪除環境。

421402073

如「 使用 Google 驗證」一文所述，VS Code 中的 Apigee 不支援 ServiceCallout 和 ExternalCallout 政策中的 Google 驗證。

無效的 HTTP 標頭錯誤：Istio ingress 會將所有傳入的目標回應切換為 HTTP2 通訊協定。由於混合訊息處理器僅支援 HTTP1，因此在呼叫 API Proxy 時，您可能會看到下列錯誤：

http2 error: Invalid HTTP header field was received: frame type: 1, stream: 1,

name: [:authority], value: [domain_name]

如果看到這則錯誤訊息，您可以採取下列任一做法來修正問題：

• 修改目標服務，以便在回應中省略主機標頭。
• 如有需要，請在 API 代理程式中使用 AssignMessage 政策移除主機標頭。

420985360

• 在入口網站上使用 SmartDocs 發布 API 時，Apigee 支援 OpenAPI 規範 3.0，但部分功能尚未支援。例如，allOf 屬性可用於結合和擴充結構定義。

  如果 OpenAPI 規格中參照的功能不受支援，在某些情況下，工具會忽略該功能，但仍會轉譯 API 參考資料文件。在其他情況下，不支援的功能會導致錯誤，導致無法順利轉譯 API 參考文件。無論是哪種情況，您都必須修改 OpenAPI 規格，避免使用不支援的功能，直到日後的版本支援為止。

• 在入口網站中使用「Try this API」時，Accept 標頭會設為 application/json，無論 OpenAPI 規格中 consumes 的值為何。

• 目前不支援多位使用者同時更新入口網站 (例如網頁、主題、CSS 或指令碼編輯)。
• 如果您從入口網站刪除 API 參考說明文件頁面，就無法重新建立該頁面；您必須刪除並重新新增 API 產品，然後重新產生 API 參考說明文件。
• 自訂 Portal 主題時，變更內容最多可能需要 5 分鐘才能完全套用。

我們會在日後的版本中將搜尋功能整合至整合式入口網站。

自訂網域不支援使用 SAML 識別資訊提供者的單一登出 (SLO) 功能。如要啟用含有 SAML 識別資訊提供者的自訂網域，請在 設定 SAML 設定時，將「登出網址」欄位留空。

• API Proxy 要求和回應計數 (針對 Proxy 和目標) 出現異常尖峰

  以下是顯示這類尖峰的範例：

  (查看較大圖片)。

  
• 由於發生錯誤，系統在短時間內會錯誤記錄計數，但會修正計數。這會發生在 API 流量減少 (導致 API Gateway 縮減規模) 的情況下。
• 如要區分實際的查詢尖峰與此問題，請參閱 API Analytics 頁面 (特別是「Proxy Performance」和「Target Performance」頁面)

受影響的指標：

• apigee.googleapis.com/proxyv2/request_count
• apigee.googleapis.com/proxyv2/response_count
• apigee.googleapis.com/targetv2/request_count
• apigee.googleapis.com/targetv2/response_count

新指標

您可以使用新的指標避免這個問題。

如需 Apigee hybrid 的相關資訊，請參閱「指標收集總覽」和「查看指標」。

解決方法：在混合型裝置上停用記錄代理程式。

因應措施：如要維持「發射後即忘」的行為，請按照下列步驟操作：

1. 將 <Response>calloutResponse</Response> 新增至 ServiceCallout。
2. 將 continueOnError 設為 true。

解決方法：請避免在 Proxy 中使用多個 SpikeArrest 政策，以免發生問題。

對於特定金鑰，如果有持續的流量，金鑰可能不會以更新的費率受到頻率限制。如果特定關鍵字在五分鐘內沒有流量，系統就會反映費率。

解決方法：如果費率必須立即生效，請使用新的參照變數重新部署 Proxy。或者，您也可以使用兩個設有不同流程變數的條件式尖峰偵測，調整費率。

針對目標傳回的非 2xx 狀態回應，可設定 API Proxy 的 API 監控功能可能會顯示「(not set)」錯誤代碼。

如果 Proxy 在使用相同目標主機的兩個或多個流程中設定兩個或多個 io.timeout.millis 值，系統只會採用一個 io.timeout.millis 值。

升級至 Apigee hybrid 1.8.x 期間，執行 apigeectl init 並確認 check-ready 成功後，如果您查看 Pod，可能會發現 Cassandra 結構定義驗證工作處於錯誤狀態。這並不會造成任何危害，您可以放心繼續執行升級程序的下一個步驟。

系統不允許將路徑相同的 Proxy 部署至附加至相同例項和環境群組的多個環境，並應傳回有關基本路徑衝突的警告訊息。但系統不會顯示任何錯誤，且部署作業似乎成功完成。

解決方法：在部署及部署後，請確認沒有與已部署的 Proxy 發生 Base Path 衝突的情況，並視需要進行修正。

嘗試儲存先前部署的 Proxy 時，部署作業可能會失敗，並顯示「修訂版本無法變更」的錯誤訊息。

解決方法：按一下「Save」按鈕旁的下拉式箭頭，然後選取「Save as new revision」。然後重新嘗試部署。

呼叫 gRPC 目標伺服器時，唯一傳回的尾隨字串是「grpc-status」尾隨字串。並從回應中移除所有其他預告片。