apache / apache/apisix-helm-chart
fix(ingress-controller): align listenerPortMatchMode chart default with controller
- Dominant language
- Go Template
- Stars
- 289
- Forks
- 282
- Avg merge
- 15h 55m
- Merged PRs (30d)
- 3
Description
## Problem
APISIX Ingress Controller 2.2.0 deliberately changed the omitted `listener_port_match_mode` default from `auto` to `off`, but the released Helm chart 1.3.0 still renders `listener_port_match_mode: auto`.
Because the chart writes the field explicitly into `config.yaml`, Helm installations use `auto` and never reach the controller's `off` fallback. The APISIX umbrella chart 2.17.0 pins controller chart 1.3.0 without overriding this value, so it inherits the same behavior.
## Why the controller default changed
During [apache/apisix-ingress-controller#2804](https://github.com/apache/apisix-ingress-controller/pull/2804), review identified the common Service-port mismatch:
- Gateway listener declares `80`.
- Kubernetes Service maps `80` to APISIX container port `9080`.
- `auto` can inject `server_port == 80`.
- APISIX evaluates the predicate against `9080`, so every affected route misses.
The controller maintainer therefore made listener-port injection opt-in by defaulting an omitted or unrecognized mode to `off`. The review reply states that nothing should start injecting predicates without the operator opting in.
The same 2.2.0 default is used by API7 Ingress Controller, and [api7/api7-helm-chart#353](https://github.com/api7/api7-helm-chart/pull/353) explicitly renders `off` to match it.
## How the chart drift occurred
- [apache/apisix-ingress-controller#2703](https://github.com/apache/apisix-ingress-controller/pull/2703) introduced the modes in 2.1.0 with `auto` as the original default.
- [apache/apisix-helm-chart#972](https://github.com/apache/apisix-helm-chart/pull/972) exposed that 2.1.0 value as `listenerPortMatchMode: auto`.
- The controller default changed to `off` in #2804.
- [apache/apisix-helm-chart#996](https://github.com/apache/apisix-helm-chart/pull/996) released 2.2.0, but its `values.yaml` diff updated only the image tag and retained `auto`. The PR did not record an intentional compatibility exception.
## Current effective values
| Installation path | Effective mode |
| --- | --- |
| Controller 2.2.0 with field omitted | `off` |
| Controller chart 1.3.0 | `auto` |
| APISIX umbrella chart 2.17.0 | `auto` |
| API7 controller chart 0.1.26 | `off` |
## Expected behavior
The controller chart should default to `off`, matching the controller's safety default. Users who intentionally rely on listener-port isolation should set `listenerPortMatchMode: auto` or `explicit`.
If maintainers choose to preserve `auto` for Helm upgrade compatibility, that divergence should instead be explicit in chart documentation and release notes, with the Service-port/container-port risk clearly documented.
## Upgrade consideration
Changing the chart default can affect users who rely on `auto` to distinguish routes by Gateway listener port. The release note should tell those users to set `config.listenerPortMatchMode: auto` explicitly before upgrading.
## Proposed acceptance criteria
- [ ] Change `charts/apisix-ingress-controller/values.yaml` default from `auto` to `off`.
- [ ] Change the ConfigMap template fallback from `auto` to `off`.
- [ ] Regenerate the chart README.
- [ ] Add or update tests proving the default rendered `config.yaml` contains `listener_port_match_mode: off`.
- [ ] Add an upgrade note for users who require `auto` or `explicit`.
- [ ] Verify the APISIX umbrella chart inherits `off` and can still override the subchart value.
- [ ] If `auto` is intentionally retained, document and test it as an approved chart-versus-binary divergence instead.
## Related tracking
- Cross-product default audit: [api7/api7-ingress-controller#462](https://github.com/api7/api7-ingress-controller/issues/462)
- Broader APISIX chart/config drift: [apache/apisix-helm-chart#997](https://github.com/apache/apisix-helm-chart/issues/997)
## Evidence
- [Controller 2.2.0 default](https://github.com/apache/apisix-ingress-controller/blob/2.2.0/internal/controller/config/config.go#L42-L60)
- [Controller injection decision](https://github.com/apache/apisix-ingress-controller/blob/2.2.0/internal/adc/translator/translator.go#L53-L114)
- [Chart 1.3.0 values](https://github.com/apache/apisix-helm-chart/blob/apisix-ingress-controller-1.3.0/charts/apisix-ingress-controller/values.yaml#L93-L96)
- [Chart 1.3.0 ConfigMap](https://github.com/apache/apisix-helm-chart/blob/apisix-ingress-controller-1.3.0/charts/apisix-ingress-controller/templates/configmap.yaml#L34-L40)
- [Umbrella chart dependency](https://github.com/apache/apisix-helm-chart/blob/apisix-2.17.0/charts/apisix/Chart.yaml#L43-L52)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with charts/apisix-ingress-controller/values.yaml and templates/configmap.yaml, then inspect the chart README and the APISIX umbrella dependency in charts/apisix/Chart.yaml. Render the chart or run the existing chart tests to verify the default config contains listener_port_match_mode: off, preserves explicit overrides, updates generated documentation, and records the upgrade guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- helm, kubernetes
- Domain
- devops, infrastructure
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 70/100