排查 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}/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}/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 模式创建的集群，系统会启用工作负载身份联合。如果您使用标准模式创建了集群，则在使用标准集群的情况下，请按照启用 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
```
输出类似于以下内容：名称： apim-ksa 命名空间： apim 标签： ... 注释： iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo.iam.gserviceaccount.com ... 映像拉取密钥：可装载密钥：令牌：事件：

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

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

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

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

bindings:
- members:
  - serviceAccount:${PROJECT}.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
    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 运行时流量的问题

有效请求失败

问题排查步骤

无效请求成功

问题排查步骤

缺少分析

其他资源

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