Support multiple bind addresses for dual-stack (IPv4 + IPv6)

未关闭
#983 1 条评论 2 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
描述清楚
活跃度
活跃
技术栈
ruby, yaml

调研方向

Start by locating the HAProxy job templates and specs that render every use of ha_proxy.binding_ip, including HTTP, HTTPS, WSS, health-check, and TCP bindings. Compare the proposed binding_ips behavior with the existing v4v6 rendering; completion should apply validated addresses across all bind sites and ensure IPv6 entries generate the intended v6only setting.

由索引模型根据 Issue 内容生成。

描述

stale

Problem

The current ha_proxy.binding_ip property accepts a single scalar address. Combined with ha_proxy.v4v6: true, it enables dual-stack by creating one IPv6 socket that also accepts IPv4 connections via the kernel's IPv4-mapped IPv6 mechanism (::ffff:x.x.x.x).

This has two drawbacks:

  1. IPv4-mapped addresses in logs -- All IPv4 client addresses appear as ::ffff:10.x.x.x because they arrive through the IPv6 socket. This may affect log parsing, ACL matching, and monitoring tools that expect plain IPv4 addresses.

  2. No separate socket option -- Some environments my require distinct IPv4 and IPv6 sockets (e.g., for independent firewall rules, clean logging, or compliance). The only workaround today is ha_proxy.frontend_config, which is fragile because it applies to all frontends, requires manually duplicating TLS/ALPN/mTLS options, and forces disabling the HTTP frontend to avoid port conflicts.

Related bug

ha_proxy.v4v6 uses if_p (presence check) instead of checking the Boolean value. Since the property defaults to false, binding_ip: "::" always renders v4v6 regardless of the property value. On most Linux stemcells this is masked by the kernel default (net.ipv6.bindv6only=0), but it is incorrect behavior.

Options

Option A: Flat address list (implemented on branch)
  • Auto-detects IPv4 vs IPv6 via IPAddr and applies v6only on IPv6 entries
  • Makes IPv6 addresses explicitly IPv6 only
  • Global scope: replaces binding_ip at all generated bind sites (HTTP, HTTPS, WSS, health checks, TCP routing, generic TCP)
  • Validates for type, duplicates, and invalid IPs
  • Rejects combination with v4v6: true
  • Simplest API for the dominant use case (0.0.0.0 + ::)
  • No explicit control over v4v6 vs v6only per address
ha_proxy:
  binding_ips:
  - 0.0.0.0
  - "::"
Option B: Per-family lists
  • Explicit control: operator chooses v4v6 or v6only per IPv6 address
  • More complex API and validation (combinatorial: what if same address in multiple lists? IPv4 in v6only?)
  • v4v6 list alongside v4 list creates overlapping socket ownership
  • Less ergonomic in BOSH ops files (nested properties)
ha_proxy:
  binding_ips:
    v4:
    - 0.0.0.0
    v4v6:
    - "::"
    v6only:
    - "::"
Option C: Flat list + mode flag
  • Keeps the simple flat list
  • Adds a single property to override the IPv6 socket behavior globally
  • Covers the rare case where v4v6 is desired on listed IPv6 addresses
  • Minimal additional complexity
ha_proxy:
  binding_ips:
  - 0.0.0.0
  - "::"
  binding_ips_v6_mode: v6only  # default, or "v4v6"
Recommendation

Option A (flat list) covers ~95% of real-world usage. Option C is a reasonable extension if explicit v4v6 control is ever needed. Option B adds complexity without a clear use case that justifies it.

+++ Additional Remarks +++

When binding_ip is set to :: and the v4v6 flag is not set or false the configuration / acceptance of IPv4 traffic depends on the kernel / stemcell configuration. This makes it non-deterministic whether IPv4 traffic is accepted when binding ::.

Proposal

When binding_ip is set to :: and the v4v6 flag is not set or false only accept IPv6 traffic by setting the v6only flag.
+++ This is can be a breaking change +++

主要语言
Ruby
星标
36
派生
84
平均合并
2 天 6 小时
30 天内合并 PR
11

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

相似的 Issue

更多 Ruby Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。