Apigee 已知问题

从 Apigee Hybrid 1.14.0 版开始，自动添加 Zipkin 跟踪标头 (x-b3-*) 的功能已移除。

不适用

如果您仅指定 httpProxy，还必须确保 *.googleapis.com 已列入 Apigee Runtime Pod 的许可名单，以便连接到这些服务。

请参阅为 API 代理配置转发代理。

Apigee 混合集群中存在 istio.io 自定义资源定义 (CRD) 可能会导致 apigee-ingressgateway-manager Pod 失败。

在 Apigee Hybrid 从旧版升级到 1.14.2 的过程中，如果存在现有的 istio.io CRD，可能会导致 apigee-ingressgateway-manager Pod 的 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 保存到本地，以防需要重新创建它们：

   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 Pod：

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

ApigeeTelemetry 可能会卡在 creating 状态。

OpenShift 安装中已出现此问题。

解决方法：修改 apigee-operator 图表模板以创建正确的 clusterrole 访问权限。

1. 修改 helm-charts/apigee-operator/templates/apigee-operators.yaml 模板文件，找到 -apigee-manager-role- clusterrole 的定义。其开头为：

   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 代理的用户。与您的 API 产品关联的应用需要更新以包含新产品，但经过验证，凭证和客户端请求详细信息不需要更改。

使用“Custom Reports”和“Stats”API 时，针对使用创收功能的安装选择“按费用类型”时出错。

解决方法：在过滤之前，在客户端提取所有费用类型。

扩缩 Istio 入站流量 Pod 可能会导致 503 错误。

扩缩 Istio 入站流量 Pod 有时可能会导致 503 错误。如果发生 503 错误，负载均衡器的日志会显示以下消息：statusDetails: backend_connection_closed_before_data_sent_to_client。

解决方法：手动扩缩 Istio 入站流量 Pod。

ESS 和 非 ESS Cassandra 凭证变换在具有增强型代理限制的组织中不起作用。

运行时流量不受影响。

使用 GCP 和 HYBRID 云服务提供商从多区域设置中获取的备份包含有关在拍摄快照时存在的所有混合区域的信息。并且，由于这些区域不再存在，因此恢复作业将与 Cassandra 的当前状态冲突，且会失败并显示以下错误：Unrecognized strategy option passed to NetworkTopologyStrategy。

使用 JavaCallout 政策时，Nimbus JOSE + JWT 库可能会导致 java.lang.ClassCircularityError。

如果您有启用了 Apigee Hybrid 的组织，并且该组织的 JavaCallout 政策使用 Nimbus JOSE + JWT 库，请勿升级到 Hybrid 1.12.4、Hybrid 1.13.3、Hybrid 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 代理名称下创建。

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 云服务提供商时，Apigee 备份作业无法上传到具有保留政策的 Cloud Storage 存储桶。备份文件可能会保留在 Cloud Storage 存储桶中，文件大小为 0 字节。

解决方法：停用 Cloud Storage 存储桶的保留政策。

341099433

apigee-logger 利用 Google IAM 服务账号将日志发送到 Cloud Logging。这是因为 FluentBit 不支持工作负载身份联合，导致 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 对每个环境实施 1,000 个基本路径的临时限制，以避免在部署 API 代理修订版本时可能发生的失败。

此限制实施后，您最多可以为每个环境部署 1,000 个 API 代理修订版本（每个修订版本包含一个基本路径）。 如果 API 代理或修订版本包含多个基本路径，则每个环境的基本路径总数不得超过 1,000。

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

如果防火墙强制所有流量通过转发代理，apigee-udca 可能会进入崩溃循环退避状态。

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 部署将失败，因为它会进入无限循环。

解决方法：使用不包含循环引用的 OpenAPI 规范 yaml。

289254725

在以下情况下，包含 OASValidation 政策的代理部署可能会失败：

• OASValidation 政策中用于验证的 OpenAPI 规范采用 YAML 格式，并且
• YAML 格式的 OpenAPI 规范包含浮点数。例如：

  schema:
  type: number
  example: 2.345

284500460

为避免增加对客户端的响应的延迟时间，应将消息日志记录政策附加到 PostClientFlowPostClientFlow。如需详细了解如何在 PostClientFlows 中使用政策，请参阅使用流控制 API 代理。

282997216

仅使用 Cassandra Jolokia 密码的字母数字字符。使用特殊字符（包括但不限于“!”“@”“#”“$”“%”“^”“&”和“*”）可能会导致 Cassandra 启动失败。

270371160

Apigee 入站流量网关仅支持 TLS1.2+，不支持早期版本的 TLS。

269139342

Apigee 组织验证不遵循 overrides.yaml 中设置的 HTTP 转发代理规则。设置 validateOrg: false 以跳过此验证。

266452840

在某些情况下，使用 Anthos Service Mesh 1.15.3-asm.6 时，Web 套接字不适用于 Apigee X 和 Apigee Hybrid。

242213234

尝试加载 API 产品时可能会返回此错误：“产品未成功加载。错误：没有来自 Apigee 连接代理的可用连接。”

在 Google Cloud 项目中启用 VPC Service Controls 并将 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 pod 出现问题，请更改 metrics 资源请求和资源限制属性，以匹配以下配置属性参考文档：指标中的默认值。

使用带有 ‑‑telemetry 标志的 apigeectl apply 应用更改：

apigeectl apply --telemetry -f overrides.yaml

260324159

在某些情况下，由于同步器中发生“套接字已关闭”错误，API 代理和共享流可能需要大约 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"

请参阅配置 Hybrid 运行时。另请参阅将内部负载均衡器与 AKS 搭配使用。

241786534

使用组织范围的 UDCA 时，MART 有时无法连接到 FluentD。组织范围的 UDCA 是 Apigee Hybrid 1.8 版中的默认设置。请参阅配置属性参考文档中的 orgScopedUDCA。

在 Apigee Hybrid 1.6.6 版中将 apigee-logger 从 fluend 迁移到 fluent-bit 后，日志记录器在使用 CentOS 或 RHEL 的 Anthos Bare Metal 上不再起作用。

当前的 apigee-logger 配置（包括活跃性探测）与 Kubernetes 运行时不兼容，导致日志未按预期发送到 Cloud Logging。此问题还会导致 apigee-logger Pod 定期崩溃。此问题会影响 AKS、Anthos Bare Metal 和其他平台上的 Apigee Hybrid 安装。请注意，在某些情况下，此问题会导致日志量过多。

在 Apigee 界面中，您无法查看、确认部署状态或管理您的归档部署（如部署 API 代理所述），也无法使用调试界面（如使用调试所述）。如需解决此问题，您可以使用 gcloud 或 API 列出环境中的所有归档部署，并使用 Debug API。

目前不支持回滚归档部署。 如需移除归档部署的某个版本，您需要重新部署旧版归档或删除环境。

421402073

Apigee in VS Code 不支持 ServiceCallout 和 ExternalCallout 政策中的 Google 身份验证（如使用 Google 身份验证中所述）。

无效的 HTTP 标头错误：Istio Ingress 会将所有传入的目标响应切换到 HTTP2 协议。由于 Hybrid 消息处理器仅支持 HTTP1，因此调用 API 代理时，您可能会看到以下错误：

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 规范，以避免使用不受支持的功能，直到将来的版本支持它为止。

• 在门户中使用“试用此 API”时，无论如何设置 OpenAPI 规范中 consumes 的值，Accept 标头都设置为 application/json。

• 目前不支持多用户同时进行门户更新（例如页面、主题背景、CSS 或脚本修改）。
• 如果您从门户中删除 API 参考文档页面，则无法重新创建该页面；您需要删除然后重新添加 API 产品，再重新生成 API 参考文档。
• 自定义门户主题背景时，更改最多可能需要 5 分钟才能完全生效。

在未来版本中，将把搜索集成到集成式门户中。

自定义网域不支持具有 SAML 身份提供商的单一退出 (SLO)。如需通过 SAML 身份提供商启用自定义网域，请在配置 SAML 设置时将“退出网址”字段留空。

• API 代理请求和响应计数（适用于代理和目标）显示异常峰值

  以下示例展示了此类峰值：

  （查看放大图片）

  
• 由于错误，系统会短暂地错误注册计数，稍后计数会更正。当 API 流量减少（导致 API 网关缩容）时，会发生这种情况。
• 如需区分请求的实际峰值与此问题，请参阅 API 分析页面（特别是代理性能和目标性能页面）

受影响的指标：

• 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，请参阅指标收集概览和查看指标。

解决方法：在 Hybrid 上停用日志记录代理。

解决方法：要保持触发和忘记行为，请执行以下操作：

1. 将 <Response>calloutResponse</Response> 添加到 ServiceCallout。
2. 将 continueOnError 设置为 true。

解决方法：避免在代理中使用多个 SpikeArrest 政策来防止出现问题。

对于特定密钥，如果存在连续流量，则该密钥的速率可能不会限制为更新后的速率。如果某特定键有 5 分钟没有流量，则速率将反映出来。

解决方法：如果速率必须立即生效，请使用新的引用变量重新部署代理。或者使用两个具有不同流变量的条件高峰控制来调整速率。

可配置 API 代理的 API Monitoring 可能会针对来自目标具有非 2xx 状态的响应显示“（未设置）”故障代码。

如果代理使用同一目标主机在两个或多个流中设置两个或多个 io.timeout.millis 值，则系统仅会遵循 io.timeout.millis 值。

在升级到 Apigee Hybrid 1.8.x 期间，运行 apigeectl init 并确认 check-ready 成功后，您可能会注意到，如果您查看 pod，则 Cassandra 架构验证作业会处于错误状态。这种情况不会造成影响，您可以放心地进入升级流程的下一步。

不允许将具有相同路径的代理部署到连接到同一实例和环境组的多个环境，系统应返回有关基本路径冲突的警告消息。系统不会显示任何错误，并且部署似乎成功了。

临时解决方法：部署时以及部署后，验证基本路径与已部署的代理不存在冲突，并根据需要进行更正。

尝试保存先前部署的代理时，部署可能会失败，并显示指出修订版本不可变的错误。

解决方法：点击保存按钮旁边的下拉箭头，然后选择保存为新修订版本。然后，重新尝试部署。

在调用 gRPC 目标服务器时，返回的唯一尾部便是“grpc-status”尾部。所有其他尾部的片段都会从响应中移除。