refactor: Standardise listener IPv6 support across endpoints

[twellck]

Description

Description

APISIX handles listener configuration inconsistently across its endpoints. node_listen and ssl.listen support flexible object/list-based definitions and automatically generate proper dual-stack (IPv4 + IPv6) listen directives when enable_ipv6 is true. Other endpoints do not:

Listener	Config Key	IPv6 support	Multi-port	Uses listen_table_insert
HTTP proxy	apisix.node_listen	Yes	Yes	Yes
HTTPS/SSL	apisix.ssl.listen	Yes	Yes	Yes
PROXY Protocol	apisix.proxy_protocol	Global only (added in #12859)	No	No
Admin API	deployment.admin.admin_listen	No	No	No
Control API	apisix.control	No	No	No
Status API	apisix.status	No	No	No
Prometheus	plugin_attr.prometheus.export_addr	No	No	No

The problem in practice

In IPv6 environments like Kubernetes, deployers currently work around this by either setting the listener IP directly to [::] (relying on OS-level dual-stack behavior, which isn't guaranteed) or injecting raw Nginx configuration snippets. For example, a Helm values workaround to get IPv6 working on admin, status, and proxy_protocol:

admin:
  ip: '"[::]"'
status:
  ip: '"[::]"'
nginx:
  configurationSnippet:
    httpSrv: |
      listen [::]:9182 ssl default_server proxy_protocol;

This should be unnecessary, setting enable_ipv6: true should be enough for all endpoints to generate proper dual-stack listen directives, just as it already does for node_listen and ssl.listen.

Proposed Change

Route all listener processing through listen_table_insert in ops.lua, which already handles IPv4/IPv6 expansion, IP validation, and duplicate detection. This would:

1. For proxy_protocol: Add full alignment with node_listen/ssl.listen, list-based listen_http/listen_https keys with IP binding and multi-port support (backward compatible with listen_http_port/listen_https_port).
2. For admin, control, status, prometheus: Process through listen_table_insert to gain automatic IPv6 support via enable_ipv6. No multi-port support needed, these remain single-endpoint listeners.

The result is one code path for all listeners instead of the current 4-5 different patterns, and enable_ipv6: true works consistently everywhere.

Implementation approach

The bulk of the work involves making listen_table_insert generic enough to handle all listener types (it currently assumes HTTP/HTTPS proxy semantics). The template changes in ngx_tpl.lua are minimal, iterating over processed listener lists instead of raw config values. Most of the diff will likely be in tests, updating them to validate IPv6 generation and the new schema for proxy_protocol. The core logic change is small since the patterns already exist in node_listen/ssl.listen processing.

Context

This was originally part of #12859, which was simplified per reviewer feedback to only add IPv6 support for PROXY Protocol. A reference implementation for the proxy_protocol portion exists on branch refactor/proxy-protocol-listener-standardization.

---

Note: AI helped format this Issue.

[Baoyuantop]

Thanks @twellck for this issue and the detailed analysis.

The inconsistency you've identified is real — enable_ipv6 only applies to node_listen and ssl.listen while the other 5 listener endpoints are left out. I traced the history: this behavior dates back to PR #341 (2019) when enable_ipv6 was first introduced. At that time APISIX only had proxy and admin server blocks, and only the proxy ports needed external exposure, so IPv6 was only added there. When control, status, and prometheus endpoints were added later, nobody went back to add IPv6 support.

I'd like to discuss a few things about the approach before implementation:

1. Loopback address IPv6 mapping
   The current listen_table_insert always appends [::] (IPv6 wildcard) when enable_ipv6=true. But control (default 127.0.0.1:9090) and prometheus (default 127.0.0.1:9091) bind to localhost — their IPv6 counterpart should be [::1] (loopback), not [::]. Feeding these endpoints through listen_table_insert without handling this would unintentionally expose internal-only interfaces to all network interfaces. This is a security concern that needs to be addressed regardless of which approach we take.

2. Scope of proxy_protocol changes
   Your reference implementation gives proxy_protocol the same full capabilities as node_listen (multi-port, multi-IP, list-based config, anyOf schema). But the typical proxy_protocol use case is one HTTP port + one HTTPS port — multi-port lists aren't really needed. For the IPv6 problem specifically, adding a few {% if enable_ipv6 then %} listen [::]:{* port *} ...{% end %} lines in the template is sufficient. Multi-port support could be discussed as a separate enhancement.

3. Suggest separating the functional fix from the refactor
   The current proposal bundles two things: (a) making enable_ipv6 work for all endpoints (functional fix), and (b) unifying all listeners under normalize_listen_conf (code refactor). I'd suggest:

• Fix the functional gap first: Without changing config formats or schemas, just modify ngx_tpl.lua to generate IPv6 listen directives for proxy_protocol / admin / control / status / prometheus when enable_ipv6=true. Use [::1] for loopback-bound listeners, [::] for wildcard. Small change.
• Unify code paths later (optional): Once the functional issue is resolved, submit the normalize_listen_conf refactor as a separate PR if the community finds it valuable.

What do you think about this breakdown? Happy to discuss further.

[twellck]

Thanks @Baoyuantop for the response! Happy on the breakdown, functional fix first with template-only changes, refactor as a follow-up.

Good catch on the [::1] vs [::] distinction for loopback-bound listeners, I'll make sure that's handled correctly.

On proxy_protocol scope, the main idea behind the reference implementation was to bring feature parity with node_listen and ssl.listen, primarily multi-IP binding (e.g. binding to specific interfaces for separate internal/external NLBs). Aligning the config format with node_listen would naturally include multi-port as well, since restricting it would mean a different schema for the same pattern. Happy to move this to a separate issue or just in separate an additional PR referencing this issue, let me know what you would prefer.

Happy to start with a PR for the template-only IPv6 fix across all endpoints and once that's done move onto refactoring.

[Baoyuantop]

Sounds good. For the proxy_protocol multi-IP/multi-port enhancement, a separate issue would be cleaner — it has its own design discussion (schema format, backward compat with listen_http_port/listen_https_port, etc.) that's worth tracking independently. You can reference this issue for context.
Looking forward to the template-only PR for the IPv6 fix. One small note: for the PR, it might be worth also including a test that validates IPv6 listen directives are generated for each endpoint when enable_ipv6: true.