跳到主要内容

排查 Manifest 转换与同步问题

如果资源应用后的行为与预期不一致，例如路由未正确创建、插件未生效，或服务无法路由流量，就需要进行排查。

当你应用 Kubernetes 资源（无论是 Gateway API、Ingress 还是 APISIX CRD）时，Ingress Controller 会将其转换为 ADC YAML，然后应用到网关：

本文介绍如何检查内存中转换后的 ADC 配置，以及实际应用到网关的配置。

检查转换后的 ADC 配置​

Ingress Controller 提供可通过浏览器访问的 debug API，用于以 JSON 格式展示从最近应用的 Gateway API、Ingress 和 APISIX CRD 资源转换得到的 ADC 配置。它可帮助你检查__配置同步到网关之前的内存状态__。

如需使用 debug API，请在 Ingress Controller 的配置文件中配置以下值：

config.yaml
enable_server: true             # 启用 debug API server
server_addr: "127.0.0.1:9092"   # Server 地址

这些值目前尚未在 Helm Chart 中暴露。如需应用变更，请修改 ConfigMap 并重启控制器 Deployment。

启用 debug API 后，可以将控制器 Pod 端口转发到本地机器：

kubectl port-forward pod/<ingress-controller-pod-name> 9092:9092 &

现在可以在浏览器中访问 127.0.0.1:9092/debug，并按资源类型检查转换后的资源，例如路由和服务。

检查已同步的网关配置​

如果使用 API7 企业版，可以直接在 API7 控制台中查看已同步资源。由 Ingress Controller 创建的资源在控制台中为只读，不能编辑。

如果使用 APISIX，可以通过 Admin API 检查已同步资源。首先将 Admin API Service 端口转发到本地机器：

kubectl port-forward service/apisix-admin 9180:9180 &

如果以 独立模式部署 APISIX，可以向 /apisix/admin/configs 发送请求，查看同步到网关的全部配置：

curl "http://127.0.0.1:9180/apisix/admin/configs" -H "X-API-KEY: ${ADMIN_API_KEY}"

如果 APISIX 使用 etcd 部署，可以向 /apisix/admin/<resource> 发送请求，查看特定资源的同步配置。例如，查看路由配置：

curl "http://127.0.0.1:9180/apisix/admin/routes" -H "X-API-KEY: ${ADMIN_API_KEY}"

更多参考信息，请参阅 Admin API。

解决插件转换错误​

当插件的 config 无法解码为对象时，Controller 会拒绝该插件，而不会以空配置发布。这可以避免格式错误的安全插件看似已同步、实际却没有执行任何策略。

升级后若资源同步失败，请检查其状态与 Controller 日志：

kubectl describe <resource-kind> <resource-name> -n <namespace>
kubectl logs deployment/<ingress-controller-deployment> -n <namespace> \
  --all-containers --since=10m | grep -iE 'plugin|unmarshal|translation|sync'

检查资源以及它引用的 PluginConfig 或 ApisixPluginConfig。每个已启用插件的 config 都必须是 YAML mapping，而不能是 scalar、list 或格式错误的 JSON。修正资源后重新应用；不要把转换后 debug 输出中缺少插件误判为成功的部分配置。