This is an automated email from the ASF dual-hosted git repository.
traky pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-ingress-controller.git
The following commit(s) were added to refs/heads/master by this push:
new bc2fe905 docs: add configuration troubleshooting reference docs (#2646)
bc2fe905 is described below
commit bc2fe905391b00f0b9bae94cdd5bf1a4d71d40bf
Author: Traky Deng <[email protected]>
AuthorDate: Thu Nov 27 16:41:04 2025 +0800
docs: add configuration troubleshooting reference docs (#2646)
---
docs/en/latest/config.json | 1 +
docs/en/latest/reference/troubleshoot.md | 56 ++++++++++++++++++++++++++++++++
2 files changed, 57 insertions(+)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 7c0c2f66..e469fdb7 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -39,6 +39,7 @@
"items": [
"reference/api-reference",
"reference/example",
+ "reference/troubleshoot",
"reference/configuration-file",
"reference/ingress-annotation"
]
diff --git a/docs/en/latest/reference/troubleshoot.md
b/docs/en/latest/reference/troubleshoot.md
new file mode 100644
index 00000000..5c8fdaed
--- /dev/null
+++ b/docs/en/latest/reference/troubleshoot.md
@@ -0,0 +1,56 @@
+---
+title: Configuration Troubleshooting
+slug: /reference/apisix-ingress-controller/configuration-troubleshoot
+description: Learn how to inspect and troubleshoot configuration translation
and synchronization in APISIX Ingress Controller.
+---
+
+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](./configuration-file.md):
+
+```yaml title="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:
+
+```shell
+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:
+
+```shell
+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:
+
+```shell
+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:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -H "X-API-KEY:
${ADMIN_API_KEY}"
+```
+
+For reference, see [Admin
API](https://apisix.apache.org/docs/apisix/admin-api/).
