Add proxy protocol v2 client-side support #979

defanator · 2025-02-17T06:34:46Z

Proposed changes

This PR introduces support for proxy protocol v2 which is available in nginx starting from versions 1.13.11 (foss) and R16 (NGINX Plus).

Primary use case is running nginx-prometheus-exporter alongside with nginx or NGINX Plus sitting behind other load balancers like AWS NLB or Google's PNLB with proxy protocol enabled. Sometimes creating dedicated listeners just for stub_status or API could be undesired, and with the proposed changes the exporter will be able to reuse existing listeners without extra effort.

Changes were tested with the following combinations of listeners:

IPv4 with proxy_protocol, IPv4 without proxy_protocol.
IPv6 with proxy_protocol, IPv6 without proxy_protocol.
Unix socket with proxy_protocol, unix socket without proxy_protocol (not that common scenario, but still supported by standard).

Implementation used: https://github.com/pires/go-proxyproto

Checklist

Before creating a PR, run through this checklist and mark each as complete.

I have read the CONTRIBUTING guide
I have proven my fix is effective or that my feature works
I have checked that all unit tests pass after adding my changes
I have ensured the README is up to date
I have rebased my branch onto main
I will ensure my PR is targeting the main branch and pulling from my branch on my own fork

github-actions · 2025-02-17T06:34:58Z

✅ All required contributors have signed the F5 CLA for this PR. Thank you!
_{Posted by the CLA Assistant Lite bot.}

defanator · 2025-02-17T06:36:34Z

I have hereby read the F5 CLA and agree to its terms

defanator · 2025-02-17T06:40:02Z

For the reference, here's the linter output from a platform I've been testing on:

nginx-prometheus-exporter % make lint
go run github.com/golangci/golangci-lint/cmd/[email protected] run --fix

nginx-prometheus-exporter % go version
go version go1.24.0 darwin/amd64

nginx-prometheus-exporter % sw_vers 
ProductName:            macOS
ProductVersion:         15.3
BuildVersion:           24D60

jjngx · 2025-05-14T14:10:26Z

@sindhushiv, this PR introduces a new 3rd party dependency (github.com/pires/go-proxyproto). It needs to be approved before we merge.

jjngx · 2025-05-15T08:30:46Z

@defanator Could you please resolve conflicts?

defanator · 2025-07-17T16:56:30Z

@jjngx sorry for slow response - I'll try to address this ASAP.

vepatel · 2025-07-29T14:21:18Z

@jjngx re #979 (comment), its Apache 2.0 👍🏼

vepatel · 2025-08-05T16:18:47Z

test nginx conf:

worker_processes 1;
pid /var/run/nginx.pid;
error_log /var/log/nginx/error.log;

events {
    worker_connections 1024;
}

http {
    access_log /var/log/nginx/access.log;
    
    # Server with proxy protocol support (port 8080)
    server {
        listen 8080 proxy_protocol;
        server_name localhost;
        
        # Extract real IP from proxy protocol headers
        real_ip_header proxy_protocol;
        set_real_ip_from 127.0.0.1;
        
        location /stub_status {
            stub_status on;
            access_log off;
        }
        
        location /test {
            return 200 "Hello from NGINX with Proxy Protocol!\n";
            add_header Content-Type text/plain;
        }
    }
    
    # Regular server without proxy protocol (port 8081)
    server {
        listen 8081;
        server_name localhost;
        
        location /stub_status {
            stub_status on;
            access_log off;
        }
        
        location /test {
            return 200 "Hello from regular NGINX!\n";
            add_header Content-Type text/plain;
        }
    }
}

start nginx docker container:

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/nginx-test/ [pr-979] docker run -d \
  --name nginx-proxy-test \
  -p 18080:8080 \
  -p 18081:8081 \
  -v "$(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro" \
  nginx:latest

cURL:

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] curl http://127.0.0.1:18081/test       

Hello from regular NGINX!

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] curl http://127.0.0.1:18080/test

curl: (52) Empty reply from server

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] curl http://127.0.0.1:18080/test --haproxy-protocol

Hello from NGINX with Proxy Protocol!

stub_status:

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] curl http://127.0.0.1:18081/stub_status             

Active connections: 1 
server accepts handled requests
 19 19 14 
Reading: 0 Writing: 1 Waiting: 0

exporter test with proxy_protocol:

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] ./nginx-prometheus-exporter \
  --nginx.proxy-protocol \
  --nginx.scrape-uri="http://127.0.0.1:18080/stub_status" \
  --web.listen-address=":9116" \
  --web.telemetry-path="/metrics"

time=2025-08-05T17:12:59.652+01:00 level=INFO source=exporter.go:126 msg=nginx-prometheus-exporter version="(version=, branch=, revision=460eaad9dfbab5d99f3296acab41d3879b2a0c8b-modified)"
time=2025-08-05T17:12:59.652+01:00 level=INFO source=exporter.go:127 msg="build context" build_context="(go=go1.24.2, platform=darwin/arm64, user=, date=, tags=unknown)"
time=2025-08-05T17:12:59.653+01:00 level=INFO source=tls_config.go:347 msg="Listening on" address=[::]:9116
time=2025-08-05T17:12:59.653+01:00 level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9116

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] curl http://127.0.0.1:9116/metrics | grep "nginx_up"

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  9632    0  9632    0     0  3187k      0 --:--:-- --:--:-- --:--:-- 4703k

# HELP nginx_up Status of the last metric scrape
# TYPE nginx_up gauge
nginx_up 1

exporter test without proxy_protocol:

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] ./nginx-prometheus-exporter \                       
  --nginx.scrape-uri="http://127.0.0.1:18081/stub_status" \
  --web.listen-address=":9116" \
  --web.telemetry-path="/metrics" &

time=2025-08-05T17:17:21.632+01:00 level=INFO source=exporter.go:126 msg=nginx-prometheus-exporter version="(version=, branch=, revision=460eaad9dfbab5d99f3296acab41d3879b2a0c8b-modified)"
time=2025-08-05T17:17:21.632+01:00 level=INFO source=exporter.go:127 msg="build context" build_context="(go=go1.24.2, platform=darwin/arm64, user=, date=, tags=unknown)"
time=2025-08-05T17:17:21.633+01:00 level=INFO source=tls_config.go:347 msg="Listening on" address=[::]:9116
time=2025-08-05T17:17:21.633+01:00 level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9116

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] curl http://127.0.0.1:9116/metrics | grep "nginx_up"

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  9630    0  9630    0     0   819k      0 --:--:-- --:--:-- --:--:--  854k

# HELP nginx_up Status of the last metric scrape
# TYPE nginx_up gauge
nginx_up 1

exporter test with proxy_protocol using envvar PROXY_PROTOCOL:

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] PROXY_PROTOCOL=true ./nginx-prometheus-exporter \
  --nginx.scrape-uri="http://127.0.0.1:18080/stub_status" \
  --web.listen-address=":9115" \
  --web.telemetry-path="/metrics" &


time=2025-08-05T17:23:17.459+01:00 level=INFO source=exporter.go:126 msg=nginx-prometheus-exporter version="(version=, branch=, revision=460eaad9dfbab5d99f3296acab41d3879b2a0c8b-modified)"
time=2025-08-05T17:23:17.461+01:00 level=INFO source=exporter.go:127 msg="build context" build_context="(go=go1.24.2, platform=darwin/arm64, user=, date=, tags=unknown)"
time=2025-08-05T17:23:17.462+01:00 level=INFO source=tls_config.go:347 msg="Listening on" address=[::]:9115
time=2025-08-05T17:23:17.462+01:00 level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9115

 ~/nginx/kubernetes-ingress/internal/nginx/test prom/ [pr-979] curl http://127.0.0.1:9115/metrics | grep "nginx_up"

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  9628    0  9628    0     0  2253k      0 --:--:-- --:--:-- --:--:-- 2350k

# HELP nginx_up Status of the last metric scrape
# TYPE nginx_up gauge
nginx_up 1

pdabelf5 · 2025-08-06T16:22:04Z

I have verified the tests @vepatel ran

defanator · 2025-08-06T20:48:01Z

Thanks @vepatel @pdabelf5 for double checking the e2e flows. I did similar testing before submitting this one + a few extras (like UNIX socket listeners).

Copilot

Pull Request Overview

This PR adds client-side support for proxy protocol v2 to the nginx-prometheus-exporter, enabling it to work with nginx instances behind load balancers that use proxy protocol. The implementation allows the exporter to send proxy protocol headers when connecting to nginx endpoints.

Adds a new command-line flag --nginx.proxy-protocol to enable proxy protocol support
Implements proxy protocol v2 header generation and transmission for TCP and Unix socket connections
Updates documentation to reflect the new functionality

Reviewed Changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 3 comments.

File	Description
go.mod	Adds dependency on `github.com/pires/go-proxyproto v0.8.1` library
exporter.go	Implements proxy protocol v2 client logic with connection wrapping and header transmission
README.md	Documents the new `--nginx.proxy-protocol` command-line flag

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

exporter.go

defanator requested a review from a team as a code owner February 17, 2025 06:34

github-actions bot added documentation Pull requests/issues for documentation dependencies Pull requests that update a dependency file labels Feb 17, 2025

defanator mentioned this pull request Feb 17, 2025

agent fails to communicate with nginx listen sockets with proxy protocol enabled nginx/agent#978

Open

mpstefan added the waiting for response Waiting for author's response label Jun 4, 2025

defanator force-pushed the proxy_proto branch from 884b361 to 460eaad Compare July 17, 2025 17:53

vepatel added this to NGINX Ingress Controller Jul 29, 2025

github-project-automation bot moved this to Todo ☑ in NGINX Ingress Controller Jul 29, 2025

vepatel moved this from Todo ☑ to In Review 👀 in NGINX Ingress Controller Jul 29, 2025

vepatel removed the waiting for response Waiting for author's response label Jul 29, 2025

vepatel approved these changes Aug 5, 2025

View reviewed changes

pdabelf5 approved these changes Aug 6, 2025

View reviewed changes

pdabelf5 added this to the v1.5.0 milestone Aug 7, 2025

pdabelf5 mentioned this pull request Aug 7, 2025

Release satelite projects nginx/kubernetes-ingress#8106

Open

7 tasks

AlexFenlon approved these changes Aug 11, 2025

View reviewed changes

danielnginx requested a review from Copilot August 14, 2025 12:57

This comment was marked as outdated.

Sign in to view

Add proxy protocol support

7e8eb6c

defanator force-pushed the proxy_proto branch from 58e8b77 to 7e8eb6c Compare August 20, 2025 22:00

Address review comments

c880254

defanator requested review from vepatel, pdabelf5, AlexFenlon and Copilot August 20, 2025 22:59

Copilot AI reviewed Aug 20, 2025

View reviewed changes

exporter.go Show resolved Hide resolved

exporter.go Outdated Show resolved Hide resolved

exporter.go Outdated Show resolved Hide resolved

Address review comments

cbaa068

pdabelf5 approved these changes Aug 21, 2025

View reviewed changes

danielnginx moved this from In Review 👀 to In Progress 🛠 in NGINX Ingress Controller Aug 21, 2025

danielnginx moved this from In Progress 🛠 to In Review 👀 in NGINX Ingress Controller Aug 21, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add proxy protocol v2 client-side support #979

Add proxy protocol v2 client-side support #979

Uh oh!

defanator commented Feb 17, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Feb 17, 2025 •

edited

Loading

Uh oh!

defanator commented Feb 17, 2025

Uh oh!

defanator commented Feb 17, 2025

Uh oh!

jjngx commented May 14, 2025 •

edited

Loading

Uh oh!

jjngx commented May 15, 2025

Uh oh!

defanator commented Jul 17, 2025

Uh oh!

vepatel commented Jul 29, 2025

Uh oh!

vepatel commented Aug 5, 2025 •

edited

Loading

Uh oh!

pdabelf5 commented Aug 6, 2025

Uh oh!

defanator commented Aug 6, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Add proxy protocol v2 client-side support #979

Are you sure you want to change the base?

Add proxy protocol v2 client-side support #979

Uh oh!

Conversation

defanator commented Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Checklist

Uh oh!

github-actions bot commented Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

defanator commented Feb 17, 2025

Uh oh!

defanator commented Feb 17, 2025

Uh oh!

jjngx commented May 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jjngx commented May 15, 2025

Uh oh!

defanator commented Jul 17, 2025

Uh oh!

vepatel commented Jul 29, 2025

Uh oh!

vepatel commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pdabelf5 commented Aug 6, 2025

Uh oh!

defanator commented Aug 6, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

defanator commented Feb 17, 2025 •

edited

Loading

github-actions bot commented Feb 17, 2025 •

edited

Loading

jjngx commented May 14, 2025 •

edited

Loading

vepatel commented Aug 5, 2025 •

edited

Loading