排查 Apigee APIM Operator for Kubernetes 的问题

本页面适用于 Apigee，但不适用于 Apigee Hybrid。

查看 Apigee Edge 文档。

本页面介绍如何排查 Apigee APIM Operator for Kubernetes 的问题。我们提供了多种工具来解决您可能遇到的所有问题。本页面介绍如何检查自定义资源的状态、使用 Logs Explorer 以及排查 Apigee 运行时流量问题。

查看自定义资源状态

Apigee APIM Operator for Kubernetes 中使用的每个自定义资源都包含一个状态对象，其中包含两个字段：

STATE：描述资源的状态。值包括 running 和 created。
ERRORMESSAGE：如果资源操作失败，则错误消息字段会填充一条说明性消息。

将自定义资源 yaml 文件应用于集群后，Kubernetes 会对底层基础架构进行相应的更改。通过检查自定义资源的状态对象，可以获得有关资源状态的信息，并发现因底层基础架构操作失败而产生的任何错误。

您可以使用以下命令检查自定义资源状态：

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

其中：

NAMESPACE：自定义资源被部署到的命名空间。
CUSTOM_RESOURCE_KIND：自定义资源的种类。
CUSTOM_RESOURCE_NAME：自定义资源的名称。

例如，以下命令会检查 apim 命名空间中名为 apim-extension-policy 的 APIMExtensionPolicy 自定义资源的状态：

kubectl -n apim get APIMExtensionPolicy apim-extension-policy-1

输出内容类似如下：

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

查看日志

本部分介绍如何使用日志来排查 Google Kubernetes Engine (GKE) 网关资源和 APIM Operator 资源的问题。

GKE 网关日志

应用 APIMExtensionPolicy 后，您在集群中创建的 GKE 网关会使用流量扩展程序进行配置。该扩展程序使用 Kubernetes 外部处理 (ext-proc) 来调用 Apigee 运行时和处理政策。在排查问题时，与 ext-proc 流量相关的日志可能会有所帮助。

查看 `ext-proc` 标注的日志

如需查看 ext-proc 标注流量的日志，请执行以下操作：

获取为 Apigee 运行时创建的后端服务的 ID：
```
kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME
  -o=jsonpath="{.metadata.annotations.networking\.gke\.io/backend-services}"
```
其中，GATEWAY_NAME 是相应 GKE 网关的名称。

后端服务的 ID 中将包含 apigee-service-extension-backend-service。
按照在后端服务上启用日志记录中的步骤启用日志记录。
如需查看日志，请在 Google Cloud 控制台中前往 Logs Explorer 页面：
日志浏览器

查看后端服务的日志消息，了解可用的标注日志条目信息，包括 service_extension_info 负载均衡器日志条目的 JSON 载荷结构。您可以使用 Logs Explorer 中的搜索字段来过滤相关信息。

以下示例是您可能会看到的失败的 ext-proc 标注的日志条目：

{
  "insertId": "s14dmrf10g6hi",
  "jsonPayload": {
    "serviceExtensionInfo": [
      {
        "extension": "ext11",
        "perProcessingRequestInfo": [
          {
            "eventType": "REQUEST_HEADERS",
            "latency": "0.001130s"
          }
        ],
        "backendTargetType": "BACKEND_SERVICE",
        "grpcStatus": "ABORTED",
        "backendTargetName": "gkegw1-2y13-apigee-service-extension-backend-service-443-yhsnrauznpwh",
        "chain": "chain1",
        "resource": "projects/$PROJECT_ID/locations/us-west1/lbTrafficExtensions/apim-extension"
      }
    ],
    "backendTargetProjectNumber": "projects/763484362408",
    "@type": "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry"
  },
  "httpRequest": {
    ...
  },
  "resource": {
    "type": "internal_http_lb_rule",
    "labels": {
      ...
    }
  },
  "timestamp": "2024-04-01T20:15:15.182137Z",
  "severity": "INFO",
  "logName": "projects/$PROJECT_ID/logs/loadbalancing.googleapis.com%2Frequests",
  "receiveTimestamp": "2024-04-01T20:15:18.209706689Z"
}

请注意，grpcStatus 字段显示 ABORTED。

APIM Operator 日志

APIM Operator 是一种 Kubernetes 操作函数，用于处理 APIM 自定义资源事件（例如创建、读取、更新和删除），并将这些事件转换为相应的 Apigee 配置。

如需查看 APIM Operator 的日志，请执行以下操作：

如需查看日志，请在 Google Cloud 控制台中前往 Logs Explorer 页面：
日志浏览器

在查询窗格中，输入类似于以下内容的查询：

resource.type="k8s_container"
resource.labels.namespace_name="apim"
labels.k8s-pod/app="apigee-apim-operator" severity>=DEFAULT

点击运行查询。
过滤后的日志条目显示在查询结果窗格中。

记下在 Google Cloud 网络服务中创建、更新或删除 APIMExtensionPolicy 时发生的任何问题，以及与 Apigee 管理平面中的 API 产品相关的问题。

示例错误如下所示：

ApimExtensionPolicy creation status400
response body:{
  "error": {
    "code": 400,
    "message": "The request was invalid: backend service https://www.googleapis.com/compute/v1/projects/... must use HTTP/2 as the protocol",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "lb_traffic_extension.extension_chains[0].extensions[0].service"
          }
        ]
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "d4e6f00ab5d367ec"
      }
    ]
  }
}

排查 APIM Operator 中的 403 访问权限错误

如果您发现状态代码 403 错误，表示存在访问权限问题，请确认以下事项：

您的 GKE 集群已启用工作负载身份联合。对于使用 Autopilot 模式创建的集群，系统会默认启用工作负载身份联合。如果您是使用 Standard 模式创建的集群，则在使用 Standard 集群的情况下，请按照启用 Workload Identity Federation for GKE 中所述启用工作负载身份联合。
Kubernetes 服务账号 (apim-ksa) 已由 Helm 安装正确批注。您可以使用以下命令进行确认：
```
kubectl describe serviceaccount apim-ksa -n NAMESPACE
```
其中，NAMESPACE 是 APIM Operator 被部署到的命名空间。

确认输出的注释字段中显示 apigee-apim-gsa@$PROJECT.iam.gserviceaccount.com。
例如：
```
kubectl describe serviceaccount apim-ksa -n apim
```
输出类似于以下内容： Name: apim-ksa Namespace: apim Labels: ... Annotations: iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo.iam.gserviceaccount.com ... Image pull secrets: Mountable secrets: Tokens: Events:

apigee-apim-gsa 服务账号具有正确的 IAM 角色及权限。您可以通过以下命令进行确认：

 gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com

服务账号必须具有 roles/iam.workloadIdentityUser 角色。

例如，以下输出显示了 roles/iam.workloadIdentityUser 角色：

bindings:
- members:
  - serviceAccount:$PROJECT_ID.svc.id.goog[/apim-ksa]
  role: roles/iam.workloadIdentityUser
etag: BwYUpeaM7XQ=
version: 1

所需角色没有设置会导致操作函数访问受限的特殊 IAM 条件。

排查 Apigee 运行时流量的问题

本部分介绍如何排查 Apigee 运行时流量的问题。以下部分介绍如何排查有效请求和无效请求的问题。

有效请求失败

如果您无法向 Apigee 运行时发送有效请求，则可能存在以下问题：

GKE 网关无法访问 Apigee 运行时。
您的 API 密钥或 JWT 凭据无效。
没有为正确的目标和环境配置 Apigee API 产品。
Apigee 运行时无法识别 Apigee API 产品。

问题排查步骤

如需排查有效请求方面的问题，请执行以下操作：

为 GKE 网关启用负载均衡器日志，并查看日志以确定扩展程序标注失败的原因。如需了解详情，请参阅 GKE 网关日志。
确认从 ext-proc 服务引用的后端服务健康状况良好。
在 Apigee 上查看 API 产品配置：
- 确认已针对正确的环境（例如 test 或 prod）启用相应的 API 产品。
- 确认资源路径与您的请求匹配。/ 或 /** 等路径将与任何路径匹配。您还可以使用 * 或 ** 通配符进行匹配。
- 确认您已为 API 产品配置开发者应用。API 产品必须绑定到开发者应用才能验证 API 密钥。
检查您向网关发送的请求：
- 确认已在 x-api-key 标头中传递了使用方密钥。
- 确保使用方密钥有效。开发者应用的凭证必须获得批准，才能用于 API 产品。

无效请求成功

如果向 Apigee 运行时发出的无效请求成功，则可能存在以下问题：

在您的 APIMExtensionPolicy 中，FailOpen 设为了 true。
未为 GKE 网关的负载均衡器设置流量扩展程序。

问题排查步骤

如需排查无效请求方面的问题，请执行以下操作：

确认服务扩展程序存在，并引用 GKE 网关的正确后端服务和转发规则。

使用以下命令查看服务扩展程序：

gcloud beta service-extensions lb-traffic-extensions describe NAME_OF_APIM_EXTENSION_POLICY --location=LOCATION  --project=PROJECT

其中：

NAME_OF_APIM_EXTENSION_POLICY：APIMExtensionPolicy 自定义资源的名称。
PROJECT：项目 ID。
LOCATION：在其中部署了网关的 GKE 集群所在的位置。

输出将如下所示：

...
extensionChains:
- extensions:
  - authority: ext11.com
    failOpen: false  # make sure this is false
    name: ext11
    service: https://www.googleapis.com/compute/v1/projects/my-project/regions/us-west1/backendServices/gkegw1-2y13-apigee-service-extension-backend-service-443-yhsnrauznpwh # Confirm this is correct
    supportedEvents:
    - REQUEST_HEADERS
    - RESPONSE_HEADERS
    - REQUEST_BODY
    - RESPONSE_BODY
    - REQUEST_TRAILERS
    - RESPONSE_TRAILERS
    timeout: 0.100s
  matchCondition:
    celExpression: 'true' # Confirm this is set
  name: chain1
forwardingRules:
- https://www.googleapis.com/compute/v1/projects/my-project/regions/us-west1/forwardingRules/gkegw1-2y13-default-internal-http-h6c1hhp1ce6q # Confirm this is the correct forwarding rule for your application load balancer
loadBalancingScheme: INTERNAL_MANAGED
name: projects/my-project/locations/us-west1/lbTrafficExtensions/apim-extension-policy-1

缺少分析

请注意，如果您在 Google Cloud 控制台中没有看到适用于 APIM Operator 的 Apigee API Analytics，可能是因为 Apigee 有一定延迟，要过几分钟才会收到相关信息。

其他资源

您还可以使用以下资源来排查 APIM Operator 和 Apigee 运行时流量的问题：

排查 Apigee APIM Operator for Kubernetes 的问题 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

查看自定义资源状态

查看日志

GKE 网关日志

查看 ext-proc 标注的日志

APIM Operator 日志

排查 APIM Operator 中的 403 访问权限错误

排查 Apigee 运行时流量的问题

有效请求失败

问题排查步骤

无效请求成功

问题排查步骤

缺少分析

其他资源

排查 Apigee APIM Operator for Kubernetes 的问题

查看 `ext-proc` 标注的日志