Configuration Troubleshooting

Troubleshooting is required if the applied behavior does not match expectations, such as routes not being created correctly, plugins not being applied, or services failing to route traffic.

When you apply a Kubernetes resource—whether a Gateway API, Ingress, or APISIX CRD—the Ingress Controller translates it into ADC YAML, which is then applied to the gateway.

This document explains how to inspect the translated ADC configurations in memory and check the configurations actually applied to the gateway.

Inspect Translated ADC Configurations

APISIX Ingress Controller provides a browser-accessible debug API that displays the translated ADC configurations, derived from the last applied Gateway API, Ingress, and APISIX CRD resources, in JSON format. It helps inspect the in-memory state before the configurations are synchronized with the gateway.

To use the debug API, configure these values in the ingress controller's configuration file:

config.yaml

enable_server: true             # Enable the debug API server
server_addr: "127.0.0.1:9092"   # Server address

These values are not yet available in the Helm chart. To apply the changes, modify the ConfigMap and restart the controller Deployment.

Once the debug API is enabled, you can access it by forwarding the controller pod’s port to your local machine:

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

You can now access the debug API in browser at 127.0.0.1:9092/debug and inspect the translated resources by resource type, such as routes and services.

Inspect Synchronized Gateway Configurations

To inspect the configurations synchronized to the gateway, you can use the Admin API.

First, forward the Admin API's service port to your local machine:

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

If you are using APISIX in standalone mode, you can send a request to /apisix/admin/configs to view all configurations synchronized to the gateway:

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

If you are using APISIX with etcd, you can send a request to /apisix/admin/<resource> to view the synchronized configurations of specific resources. For instance, to view the route configuration:

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

For reference, see Admin API.

Gateway API Routes Return 404 After Upgrade

After upgrading to APISIX Ingress Controller 2.1.0, Gateway API HTTPRoute or GRPCRoute resources may return 404. This can happen when Gateway listener ports do not match the ports that APISIX actually listens on.

In the default listener_port_match_mode: auto mode, the Ingress Controller may inject a server_port route variable from the matched Gateway listener ports. The server_port variable is evaluated by APISIX against its actual listening port, such as 9080 or 9443. If the Gateway listener uses 80 or 443 but the gateway Service maps those ports to 9080 or 9443, the route may not match.

To resolve the issue, use one of the following approaches:

• Set listener_port_match_mode to "off" in the controller configuration to disable server_port route-var injection.
• Configure APISIX to listen on the same ports declared in the Gateway listeners.