bug: shared Ingress Controller defaults differ across binaries, Helm charts, and docs

Problem

API7 Ingress Controller and Apache APISIX Ingress Controller share the same config.yaml structure, and the shared documentation presents one set of defaults. However, the two controller binaries and their two Helm charts currently produce different defaults for several non-provider fields.

Most users install the controllers through Helm, so these differences change effective behavior depending on the selected controller and installation path. We should choose canonical defaults for common fields, align the implementations where appropriate, and document any intentional installation-specific differences.

Scope and versions

This audit covers the active Ingress Controller 2.1.0 documentation and the releases that deploy controller 2.1.0:

• Apache APISIX Ingress Controller 2.1.0
• API7 Ingress Controller 2.1.0
• Apache apisix-ingress-controller chart 1.2.x
• API7 api7-ingress-controller chart 0.1.x

provider.type is intentionally excluded. listener_port_match_mode is APISIX-only and should remain explicitly documented as product-specific.

Default differences

Field	APISIX binary	API7 binary	APISIX Helm	API7 Helm
leader_election_id	apisix-ingress-gateway-leader	apisix-ingress-gateway-leader	apisix-ingress-controller-leader	apisix-ingress-controller-leader
leader_election.lease_duration	30s	30s	Declares 15s, but effective value is 30s because the rendered key is ignored	15s
leader_election.renew_deadline	20s	20s	Declares 10s, but effective value is 20s because the rendered key is ignored	10s
server_addr	:9092	:9092	Not emitted; effective :9092	127.0.0.1:9092
provider.sync_period	1h	0	1m	1h
webhook.enable	false	false	true	true

The remaining literal values align, but some still have chart-control or documentation problems described below.

Additional findings

APISIX Helm renders invalid leader-election keys

The APISIX chart renders:

leader_election:
  leaseDuration: 15s
  renewDeadline: 10s
  retryPeriod: 2s

The controller accepts lease_duration, renew_deadline, and retry_period. It uses non-strict yaml.Unmarshal, so the camelCase keys are silently ignored. This means all three APISIX Helm overrides are ineffective. A focused upstream issue should track that chart defect.

Hidden Helm fallback values also drift

The chart templates contain fallback literals that differ from values.yaml:

• APISIX: values.yaml uses 1m, while the template fallback is 1s.
• API7: values.yaml uses 1h, while the template fallback is 0s.

Helm configuration surfaces differ

• APISIX Helm does not expose or emit enable_server or server_addr.
• Both charts hard-code the webhook certificate filename, key filename, and directory when the webhook is enabled.
• API7 correctly omits listener_port_match_mode because the API7 binary does not support it.

Some differences may be intentional

Both binaries default the admission webhook to disabled, while both charts enable it and provision the required certificates and Kubernetes resources. This can be a valid installation-context override and should be documented as such rather than automatically copied into the raw binary default.

Changing leader_election_id also needs upgrade planning because replicas using different election IDs can participate in separate elections.

Related issue

• #458 covers the runtime behavior caused by API7's binary default of sync_period: 0. It should remain the implementation issue for that runtime bug. This issue tracks the broader default-alignment decision and should not duplicate #458.

Proposed acceptance criteria

• Decide canonical values for every common divergent field.
• Record any approved binary-versus-Helm differences, especially webhook.enable.
• Align API7 controller defaults and sample configuration with the decisions.
• Align API7 Helm values and template fallbacks with the decisions.
• Track and cross-link the corresponding APISIX Helm changes.
• Update the shared Ingress Controller configuration reference after the engineering decisions are implemented.
• Correct the documentation for secure_metrics, sync_period, and init_sync_delay.
• Add tests that render the default charts, load the resulting config.yaml through the real controller parser, reject unknown fields, and assert the effective defaults.
• Add upgrade guidance if leader_election_id changes.

Evidence

• APISIX controller defaults
• API7 controller defaults
• APISIX chart values
• APISIX chart template
• API7 chart values
• API7 chart template

Start with the linked controller config.go files and the APISIX and API7 chart values.yaml and templates/configmap.yaml. Render both default charts, load each config.yaml through the real controller parser, and compare the effective defaults with the shared documentation and issue #458. Done means canonical values and intentional differences are decided, implementations and docs are aligned, and parser-based chart tests plus upgrade guidance are added.