apache / apache/apisix

support IPv4/IPv6 dual-stack for admin_listen

Open
#13,744 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Lua
Stars
17.1k
Forks
2.9k
Avg merge
3d 16h
Merged PRs (30d)
63

Description

### Description

Problem
deployment.admin.admin_listen currently only accepts a single {ip, port} object. Attempting the array form (to listen on both IPv4 and IPv6 on the same port):
```yaml
listen:
- ip: 0.0.0.0
port: 9180
- ip: "[::]"
port: 9180
```
is silently ignored — APISIX falls back to the default 0.0.0.0:9180 (IPv4 only). Verified against current master source:

apisix/cli/ops.lua reads only admin_listen.ip / admin_listen.port scalars
apisix/cli/ngx_tpl.lua emits a single listen {* admin_server_addr *}; So there is no way to run the Admin API on a dual stack today.
Root cause
The address is built as one ip:port string; the template has no loop, and the port-conflict checker rejects reusing one port across addresses.

Proposal
Make admin_listen accept either the existing object or an array of {ip, port}. The CLI collects all addresses, the template emits one listen per address, and the port-conflict check allows the same port to be reused across addresses of the same service (required for dual-stack). Backward compatible with the single-object form.

Related
Supersedes / relates to #7972 (IPv6 on control plane, closed as not planned, no fix shipped).

I'd like to contribute a PR with this change plus a CLI test.

Contributor guide

Open the contributing guide

Research direction

Start with apisix/cli/ops.lua and apisix/cli/ngx_tpl.lua, then locate the existing port-conflict check and current CLI tests. Compare the scalar admin_listen path with the proposed array form. Done means both forms remain compatible, two addresses can share a port for this service, and a CLI test covers dual-stack generation.

Written by the indexing model from the issue text.

Assessment

Tech stack
lua, nginx
Domain
cli, networking
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.