apache / apache/apisix-helm-chart

fix(ingress-controller): align listenerPortMatchMode chart default with controller

Open
#1,001 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.