feat: add unified API server with debugging capabilities #2550

Revolyssup · 2025-09-09T18:18:38Z

Goals:

Provide an API endpoint for debugging.
Provide an API that generates translated ADC configurations based on the latest Gateway API/Ingress/CRD resources for inspection and debugging, outputting them in JSON.
Provide a homepage guide. Use pure HTML to create a simple title and link list.

Solution:

Uses the underlying store that adc uses to sync data as the store for debug handler.
Create a new runnable Server that registers handlers on it and runs the server.

Screencast.From.2025-09-12.15-01-20.mp4

What this PR does / why we need it:

Pre-submission checklist:

Did you explain what problem does this PR solve? Or what new features have been added?
Have you added corresponding test cases?
Have you modified the corresponding document?
Is this PR backward compatible? If it is not backward compatible, please discuss on the mailing list first

Revolyssup · 2025-09-09T18:32:16Z

internal/provider/apisix/provider.go

-		syncCh:     make(chan struct{}, 1),
+		client: cli,
+		// TODO: Maybe pass port/address from external configuration
+		adcdebugserver: common.NewADCDebugServer(cli.Store, cli.ConfigManager, 8432),


I don't think it should be needed to make this port configurable. Maybe we can hardcode it to some value.

AlinsRan · 2025-09-10T01:13:00Z

I don't think it should be a standalone server, rather than a part of the ingress controller API.

AlinsRan · 2025-09-12T02:27:10Z

I don't think it should be a standalone server, rather than a part of the ingress controller API.

Suggestion: Move the debug API into the unified Ingress Server

In the current implementation, the debug HTTP server is started directly inside the provider.
While this works, it introduces several issues:

Tight coupling of responsibilities: The provider’s job is to synchronize resources, not to start its own HTTP server.
Lack of configurability: Port, paths, authentication, etc. are “black-boxed” inside the provider and cannot be configured or extended externally.
Harder to extend: If other components later need to expose debug endpoints, you will end up with multiple scattered servers.

A cleaner approach is to:

Start a unified api server at the Ingress Server layer, e.g.:

  srv := NewServer(":9090")
  srv.Register(&addcDebugAPI{})
  srv.Register(&systemAPI{})
  mgr.Add(srv)

Let each component (including the provider) only implement a RegisterHandlers/DebugProvider interface to attach its handlers, without starting its own server.
This way, port, authentication, middleware, etc. can be configured in one place, and the server lifecycle follows the manager.

Revolyssup · 2025-09-12T09:36:54Z

I don't think it should be a standalone server, rather than a part of the ingress controller API.

Suggestion: Move the debug API into the unified Ingress Server

In the current implementation, the debug HTTP server is started directly inside the provider. While this works, it introduces several issues:

Tight coupling of responsibilities: The provider’s job is to synchronize resources, not to start its own HTTP server.

Lack of configurability: Port, paths, authentication, etc. are “black-boxed” inside the provider and cannot be configured or extended externally.

Harder to extend: If other components later need to expose debug endpoints, you will end up with multiple scattered servers.

A cleaner approach is to:

Start a unified api server at the Ingress Server layer, e.g.:
  srv := NewServer(":9090")
  srv.Register(&addcDebugAPI{})
  srv.Register(&systemAPI{})
  mgr.Add(srv)
Let each component (including the provider) only implement a RegisterHandlers/DebugProvider interface to attach its handlers, without starting its own server.

This way, port, authentication, middleware, etc. can be configured in one place, and the server lifecycle follows the manager.

done

ronething · 2025-09-15T07:45:45Z

internal/manager/server/server.go

+func (s *Server) Register(pathPrefix string, registrant provider.RegisterHandler) {
+	subMux := http.NewServeMux()
+	registrant.Register(pathPrefix, subMux)
+	s.mux.Handle(pathPrefix+"/", http.StripPrefix(pathPrefix, subMux))
+	s.mux.HandleFunc(pathPrefix, func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, pathPrefix+"/", http.StatusPermanentRedirect)
+	})
+}


The debug server currently has no authentication mechanism, making it accessible to anyone who can reach the endpoint. Should we consider incorporating certain authentication mechanisms?

The original requirement was to return simple UI friendly HTML. Adding authentication will mean adding another page for login. Maybe we can use cookie based authentication and add one more simple login html page.

Check if cookie has INGRESS-DEBUG_TOKEN. If present then serve normally.

If not present then redirect to login page. This will also be a simple HTML page with just input box to enter debug token. This debug token will be set in the static configuration for ingress and can be copied from there and pasted here. User clicks login and this value be just stored in the cookie if matches and user will be logged in.

@bzp2010 @ronething @AlinsRan What do you think?

I think it's enough not to expose the port, just like the control-api.

I think it's enough not to expose the port, just like the control-api.

It might be a bit different. This debug server has exposed SSL/Consumer resources, but the control-api does not.

It might be a bit different. This debug server has exposed SSL/Consumer resources, but the control-api does not.

You're right.

I think the only k8s native way to enable/disable this dynamically will be to use some existing CR for it. But that might be an overkill. I think we should opt for one of the two ways:

Just disable this server by default and have it enabled statically only and not dynamically. It's a debug server, I don't know if dynamically enabling/disabling it is good enough use case. This is the simplest and safest.

Just have a single login page that expects a statically defined key as recommended above.

If it's okay to enable/disable this statically then I recommend the first way is good enough or else it will be overengineering. Later if use case emerges about dynamically enabling/disabling, we can spend some thought here.

Yes, that's exactly what I was thinking. A simple static config.

However, I must confirm whether the restart required to enable this feature would disrupt the current "state". Specifically, can we guarantee consistent results based on unchanged configurations? We need to ensure that the restart does not corrupt any potentially existing in-memory state, thereby preventing the debugging of previously existing issues.

For example, we sometimes encounter problems that resolve after a restart, making it impossible to analyze the root cause.

Can anyone answer this question?

It’s not possible to guarantee the preservation of “state” across a restart.
The controller’s declarative configuration state (stored in Kubernetes/etcd via CRDs) is automatically rebuilt after a restart, but any runtime in-memory state (caches, queues, goroutine stacks, etc.) will inevitably be lost.

For an ingress controller, a restart is typically the last-resort mechanism to recover state, so if you need to debug live in-memory data, it will naturally no longer be available after restarting.

At present, for security and simplicity reasons, we recommend keeping the debug API disabled by default and enabling it only via static configuration.
If there is a strong need to inspect runtime state in the future, we can revisit supporting dynamic enablement or enabling it up front with proper authentication.

done. added the boolean in static config.

The state itself isn't critical, but it would be preferable if you could confirm it doesn't impact configuration generation.

The key point is For a given input of Kubernetes resources, always produce a fixed output. This includes how to handle conflicting resources (determine the priority), how to sort resource lists, and so on. This process already exists within AIC, such as during full synchronization at startup. We can ignore those changes triggered by reconciliation tasks.
If these could be leveraged for debugging functionality, that would be excellent.

internal/provider/apisix/provider.go

AlinsRan · 2025-09-16T07:29:04Z

config/samples/config.yaml

 metrics_addr: ":8080"                   # The address the metrics endpoint binds to.
                                        # The default value is ":8080".
+enable_server: false                    # The debug API is behind this server which is disabled by default for security reasons.
+server_addr: ":9092"


127.0.0.1?
Should we emphasize the purpose of debugging on the fields?

binded to localhost.

The purpose is generic. Although currently it's to debug the in memory state of adc config. Maybe we can add a list in the comment.

/debug can be used to debug in-memory state of translated adc configs to be synced with data plane.
....later if handlers are added, we can extend the list

Copilot

Pull Request Overview

Adds an ADC debug server with REST API endpoints to provide debugging capabilities for APISIX Ingress Controller configurations. The server exposes translated ADC configurations in JSON format for inspection and troubleshooting.

Creates a new unified API server with debugging endpoints
Implements HTML-based navigation interface for browsing ADC configurations
Integrates debug server as an optional component in the controller manager

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
internal/provider/register.go	Adds RegisterHandler interface for HTTP handler registration
internal/provider/provider.go	Extends Provider interface to embed RegisterHandler
internal/provider/common/adcdebugserver.go	Implements ADCDebugProvider with HTML templates and JSON endpoints
internal/provider/apisix/provider.go	Implements Register method to setup debug handlers
internal/manager/server/server.go	Creates new HTTP server with handler registration capabilities
internal/manager/run.go	Integrates debug server into controller manager
internal/controller/config/types.go	Adds server configuration fields
internal/controller/config/config.go	Sets default server address in configuration
internal/adc/client/client.go	Initializes ADCDebugProvider with shared store and config manager
config/samples/config.yaml	Documents server configuration options

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-09-17T01:36:01Z

internal/provider/common/adcdebugserver.go

+		</html>
+	`)
+
+	_ = tmpl.Execute(w, struct {


Error from template execution is being ignored. This could lead to silent failures when rendering HTML responses. Consider handling the error appropriately, either by logging it or returning an HTTP error response.

Copilot · 2025-09-17T01:36:02Z

internal/provider/common/adcdebugserver.go

+        </html>
+    `)
+
+	_ = tmpl.Execute(w, struct {


Template execution errors are being ignored in multiple locations. This could lead to silent failures when rendering HTML responses. Consider handling these errors appropriately, either by logging them or returning HTTP error responses.

Copilot · 2025-09-17T01:36:02Z

internal/provider/common/adcdebugserver.go

+		</html>
+	`)
+
+	_ = tmpl.Execute(w, struct {


Template execution errors are being ignored in multiple locations. This could lead to silent failures when rendering HTML responses. Consider handling these errors appropriately, either by logging them or returning HTTP error responses.

Copilot · 2025-09-17T01:36:02Z

internal/provider/common/adcdebugserver.go

+		</html>
+	`)
+
+	_ = tmpl.Execute(w, struct {


Template execution errors are being ignored in multiple locations. This could lead to silent failures when rendering HTML responses. Consider handling these errors appropriately, either by logging them or returning HTTP error responses.

AlinsRan · 2025-09-17T01:36:26Z

internal/provider/common/adcdebugserver.go

+					asrv.pathPrefix, configNameEncoded, url.QueryEscape(resourceType), url.QueryEscape(svc.ID)),
+			})
+		}
+	case "consumers":


Avoid using hard coding.

apisix-ingress-controller/api/adc/types.go

Lines 80 to 88 in 4e1bd6e

const (

TypeRoute = "route"

TypeService = "service"

TypeConsumer = "consumer"

TypeSSL = "ssl"

TypeGlobalRule = "global_rule"

TypePluginMetadata = "plugin_metadata"

)

replaced with adctypes

…ress-controller into revolyssup/api-adc

config/samples/config.yaml

internal/provider/common/adcdebugserver.go

ronething

lgtm.

Revolyssup added 3 commits September 9, 2025 23:41

feat: add adc debug server

a00cc1e

remove redundant

abf96a4

add comment

e384cc3

Revolyssup marked this pull request as draft September 9, 2025 18:18

add license and fix lint

2b38495

Revolyssup commented Sep 9, 2025

View reviewed changes

Revolyssup requested review from AlinsRan and bzp2010 September 9, 2025 18:33

fix lint

0dc2c83

Revolyssup marked this pull request as ready for review September 9, 2025 19:42

Revolyssup added 2 commits September 12, 2025 15:02

f

8516c42

remove redundant

2c7bfbd

Revolyssup changed the title ~~feat: add adc debug server~~ feat: add unified API server with debugging capabilities Sep 12, 2025

Revolyssup added 2 commits September 12, 2025 15:29

remove logger

3561e6a

change adcdebugserver to adcdebugprovider

933befb

ronething reviewed Sep 15, 2025

View reviewed changes

AlinsRan reviewed Sep 15, 2025

View reviewed changes

internal/provider/apisix/provider.go Outdated Show resolved Hide resolved

Revolyssup added 2 commits September 15, 2025 14:43

move adcprovider to adcclient

c6ad03f

f

9e48671

AlinsRan reviewed Sep 16, 2025

View reviewed changes

Update config.yaml

e1f9c52

ronething mentioned this pull request Sep 16, 2025

test: abstract gateway proxy configuration acquisition #2554

Closed

Update config.yaml

ef5851f

AlinsRan requested a review from Copilot September 17, 2025 01:35

Copilot AI reviewed Sep 17, 2025

View reviewed changes

AlinsRan reviewed Sep 17, 2025

View reviewed changes

remove hardcoding

324e684

Revolyssup added 2 commits September 17, 2025 12:28

Merge branch 'revolyssup/api-adc' of github.com:Revolyssup/apisix-ing…

2248f46

…ress-controller into revolyssup/api-adc

use adc types

ae76e77

AlinsRan approved these changes Sep 17, 2025

View reviewed changes

AlinsRan requested a review from ronething September 17, 2025 09:38

bzp2010 reviewed Sep 17, 2025

View reviewed changes

config/samples/config.yaml Show resolved Hide resolved

internal/provider/common/adcdebugserver.go Show resolved Hide resolved

ronething approved these changes Sep 18, 2025

View reviewed changes

Revolyssup merged commit b47ed04 into apache:master Sep 18, 2025
24 of 25 checks passed

Revolyssup mentioned this pull request Sep 23, 2025

feat: add adc debug server api7/api7-ingress-controller#270

Merged

12 tasks


	const (
	TypeRoute = "route"
	TypeService = "service"
	TypeConsumer = "consumer"
	TypeSSL = "ssl"
	TypeGlobalRule = "global_rule"
	TypePluginMetadata = "plugin_metadata"
	)

feat: add unified API server with debugging capabilities #2550

feat: add unified API server with debugging capabilities #2550

Uh oh!

Conversation

Revolyssup commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it:

Pre-submission checklist:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlinsRan commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AlinsRan commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Revolyssup commented Sep 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Revolyssup Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bzp2010 Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bzp2010 Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Revolyssup Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Revolyssup commented Sep 9, 2025 •

edited

Loading

AlinsRan commented Sep 10, 2025 •

edited

Loading

AlinsRan commented Sep 12, 2025 •

edited

Loading

Revolyssup Sep 15, 2025 •

edited

Loading

bzp2010 Sep 15, 2025 •

edited

Loading

bzp2010 Sep 15, 2025 •

edited

Loading

Revolyssup Sep 16, 2025 •

edited

Loading