Added proxy protocol support settings

[pantherra]

Hello again. After syncing my fork with an upcoming changes - I merged my local changes to enable support of the proxy protocol v2 settings on the Apache APISIX.
I tested it on my installation and it works fine. It is listed in the reference: https://docs.api7.ai/apisix/networking/port-reference/

[pantherra]

@AlinsRan could you please review this? I'm using it on the production setup - and it proofs the concept.

[AlinsRan]

please use lowerCamelCase

[AlinsRan]

It does not conflict with HTTP or HTTPS, why do we need to share a port?It does not conflict with HTTP or HTTPS, we should add a new service.port.

[pantherra]

Yes, it doesn't conflict. But when you enable proxy protocol on the network load balancer in front of the apache apisix (I'm using Oracle cloud) https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol/
From the documentation of the network load balancer:
"For TCP applications using PROXY protocol v2, NLB adds a PROXY protocol v2 header to each inbound TCP connection."
So if you enable ppv2 on the nlb but your upstream (apisix) cannot accept ppv2 header in the tcp - then it will be rejected. That why we need to change default port on the service that exposes gateway to ports that support ppv2 tcp header.

[pantherra]

I don't know why, but apache apisix won't let you setup proxy protocol port on the same port as node (80/443).
That why I added if statement.

[atillaqb]

@AlinsRan the case is fixed)

[DamiaPoquet]

There are already two PR open for this same objective:

• feat: re-enable proxy-protocol configuration nodes #756
• feat: add PROXY protocol support  #813

Would be nice to have any of them merged. It is extremely important for cloud deployments (AWS, GCP, Azure...) in which APISIX runs behind a L4 load balancer. Bumping for visibility.

[bg-ts]

@AlinsRan any plans on having any of those PRs merged any time soon?

[pantherra]

Looks good.

[DamiaPoquet]

@AlinsRan is this something planed to be taken care of? thanks.

[Baoyuantop]

Exposing APISIX's proxy_protocol HTTP/HTTPS listeners in the chart is a reasonable direction.

The main unresolved issue is the Service exposure model from the previous review thread: with apisix.proxyProtocol.enabled=true, the current diff changes the existing apisix-gateway / apisix-gateway-tls targetPort from the normal HTTP/TLS ports to the proxy protocol ports, instead of adding dedicated service ports. That changes the protocol semantics of the existing Service and does not allow users to expose normal HTTP/HTTPS and PROXY protocol HTTP/HTTPS at the same time.

Please first sync with master to resolve the merge conflict and fix the current failed/cancelled CI. Then please adjust the chart to add dedicated proxy protocol service ports/values, or clearly document and test why replacing the existing targetPort is the intended behavior. Please also add Helm rendering coverage for enabled=false, enabled=true, and custom listen_http_port/listen_https_port values. The unrelated formatting changes in values.yaml should be removed to keep the PR focused.

[pantherra]

@Baoyuantop Hello! I did it intentionally because:

1. Backend Support is Required
   You cannot send a PPv2 header to a standard HTTP/S server unless that server (or a reverse proxy in front of it like NGINX, HAProxy, or Envoy) is explicitly configured to parse the PROXY protocol. If an unmodified web server receives a binary PPv2 header, it will treat it as part of the actual HTTP request payload, which will either break the request or cause the TLS handshake to fail.

2. Port Sharing Restrictions
   If your backends need to accept both regular HTTP traffic and PROXY-forwarded traffic, they must listen on separate ports. You cannot mix raw client traffic and PPv2 traffic on the exact same port unless your server utilizes a specialized listener capable of auto-detecting and demultiplexing the PROXY protocol signature from incoming bytes.
   OCI & Apache APISIX Test Case

I verified this behavior while testing within the Oracle Cloud Infrastructure (OCI) environment using Apache APISIX tightly coupled with a cloud load balancer (L4 or L7).

• The Setup: When you provision a Kubernetes Service via annotations, you define the type of cloud load balancer OCI creates—either an L4 load balancer with PPv2 support or an L7 load balancer without it.
• The Conflict: If you configure the OCI load balancer with PPv2 support via annotations, the backend service (APISIX's NGINX) must explicitly expect a PPv2 handshake on those designated ports. If it doesn't, NGINX will reject the connection and break all incoming traffic.
• The Outcome: Because port sharing is impossible here, you must set up dedicated ports and a dedicated service for PPv2. To preserve plain HTTP/S traffic, you have to spin up a completely separate L7 cloud load balancer pointing to a different Kubernetes Service and APISIX NGINX ports. This ultimately results in two distinct public IP addresses. Therefore, enabling PROXY Protocol v2 essentially replaces standard HTTP/S handling on those entry points rather than complementing it.

The East-West Traffic Problem
The biggest issue I observed with a global, ingress-wide PPv2 setup involves East-West (inter-cluster) traffic:
If you target an Ingress that has PPv2 enabled globally, internal cluster communication will fail. The internal Kubernetes routing mechanism short-circuits the traffic and bypasses the cloud load balancer entirely. Consequently, the internal service receives plain HTTP/S traffic without the expected PPv2 initial handshake. Because APISIX's NGINX cannot parse this raw traffic on a PPv2-designated port, the connection fails.

[olehpalii-nc]

The East-West Traffic Problem
The biggest issue I observed with a global, ingress-wide PPv2 setup involves East-West (inter-cluster) traffic:
If you target an Ingress that has PPv2 enabled globally, internal cluster communication will fail. The internal Kubernetes routing mechanism short-circuits the traffic and bypasses the cloud load balancer entirely. Consequently, the internal service receives plain HTTP/S traffic without the expected PPv2 initial handshake. Because APISIX's NGINX cannot parse this raw traffic on a PPv2-designated port, the connection fails.

I was able to overcome that particular problem in OCI by setting oci.oraclecloud.com/ingress-ip-mode: "proxy" (Specifying_IPMode).

Other than that, I can confirm that ApiSix installed from helm chart with changes from this PR works well with OCI Network Load Balancer with PPv2 protocol enabled. It would be nice to have this PR finalized and merged so we can use upstream chart instead of relying on local copy.

[Baoyuantop]

Hi @pantherra, could you please resolve the merge conflicts and get the CI passing? Once that’s done, we can continue with the review.

[pantherra]

@Baoyuantop fixed.