smengcl commented on code in PR #10981: URL: https://github.com/apache/ozone/pull/10981#discussion_r3755752400
########## hadoop-hdds/docs/content/design/ipv6-support.md: ########## @@ -0,0 +1,439 @@ +--- +title: IPv6 Support +summary: Enable Ozone on dual-stack and IPv6-only networks without changing IPv4 defaults. +date: 2026-08-04 +jira: HDDS-15763 +status: draft +author: Siyao Meng +--- + +<!-- + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. See accompanying LICENSE file. +--> + +# Summary + +This proposal enables Apache Ozone services and clients to operate on dual-stack and IPv6-only networks. It preserves +existing IPv4 defaults, makes IPv6 activation explicit, defines one canonical host and port representation, and requires +end-to-end validation of HA, security, data, administration, and observability paths before IPv6 is considered +supported. + +# Problem statement + +Ozone uses addresses across Hadoop RPC, gRPC, Ratis, HTTP, command-line tools, configuration, and service metadata. Some +paths already accept IPv6, but other paths force the JVM to IPv4, concatenate a host and a port with `:`, or parse an +endpoint with `String.split(":")`. An IPv6 literal contains colons, so these assumptions can produce an ambiguous or +invalid endpoint such as `2001:db8::10:9862`. + +Fixing one parser is not sufficient. A cluster can start successfully and still fail later during leader failover, +certificate enrollment, delegation-token use, an administrative command, or metrics collection. Ozone therefore needs a +single address contract and a test matrix that covers complete service paths. + +The proposal uses an incremental approach: + +1. Do not force the JVM into an IPv4-only networking mode. +2. Preserve current IPv4 bind defaults and let operators opt into IPv6. +3. Store hosts and ports separately in code and use bracket-aware parsing and formatting at text boundaries. +4. Qualify dual-stack and IPv6-only operation independently, including secure and HA deployments. + +# Goals + +- Run SCM, OM, datanodes, Recon, S3 Gateway, HTTPFS Gateway, OzoneFS clients, and administrative clients on dual-stack + and IPv6-only networks. +- Preserve existing IPv4 behavior and configuration defaults. +- Support DNS names, IPv4 literals, and IPv6 literals in every documented endpoint setting. +- Make Hadoop RPC, gRPC, Ratis, HTTP/HTTPS, OzoneFS, S3 Gateway, HA failover, and administrative paths IPv6-safe. +- Define secure-mode requirements for Kerberos, delegation tokens, TLS certificates, and endpoint verification. +- Validate replicated and erasure-coded data paths over IPv6. +- Preserve access to Prometheus and JMX metrics over IPv6. +- Provide repeatable CI coverage and operator documentation for IPv6 configuration and limitations. + +# Non-goals + +- Change rack or network-topology semantics, or add IPv6 CIDR routing logic to SCM. +- Change existing bind defaults from `0.0.0.0` to `::`. +- Prefer raw IP literals over DNS names for Kerberos or TLS identities. +- Link-local and scoped IPv6 addresses are not supported as persistent cluster identities. Advertised endpoint settings + reject them because scope identifiers are interface-local and cannot be encoded in X.509 IP subject alternative names. +- Replace every address string with a new Protobuf type in the first delivery. +- Guarantee IPv6 support in applications or network services outside the Apache Ozone project. Ozone will document and + test the public integration points that it uses. + +# Technical description + +## Support profiles + +Ozone will distinguish the following network profiles: + +- **IPv4:** Use existing listener defaults and IPv4 routing. Clients use IPv4 or DNS names that resolve to IPv4. +- **Dual-stack:** Provide IPv6-capable listeners and both address families. Clients use IPv4, IPv6, or DNS names with A + and/or AAAA records. +- **IPv6-only:** Provide IPv6 listeners and routing with no usable IPv4 fallback. Clients use IPv6 or DNS names that + resolve to IPv6. + +A deployment is not IPv6-only merely because a client prefers IPv6. The qualification environment must remove or block +IPv4 connectivity so that a test cannot silently fall back to IPv4. + +## Address representation + +Text boundaries must follow these rules: + +- **Host-only configuration:** Accept a DNS name, IPv4 literal, or bare IPv6 literal such as `::`. Keep the canonical + host value free of URI brackets. +- **Host and port configuration:** Accept `host:port`, `ipv4:port`, or `[ipv6]:port`. Enclose IPv6 literals in brackets + in the canonical output. +- **URI authority:** Accept and emit an RFC-compliant authority, including `[ipv6]:port`. +- **HTTP `Host` header:** Accept a DNS name, IPv4 literal, `[ipv6]`, or `[ipv6]:port`. Remove brackets before subsequent + matching. +- **Scoped IPv6:** Reject an address containing a zone identifier, such as `fe80::1%eth0`, in every advertised endpoint + setting. Do not strip the identifier and advertise the remaining address. +- **In-memory endpoint:** Keep the host and port as separate values. Combine them only when crossing a text boundary. + +An unbracketed IPv6 literal followed by a port is ambiguous and will not be an accepted endpoint form. Code must not use +`String.split(":")`, `lastIndexOf(':')`, or string concatenation to parse or construct a network authority. + +Shared helpers will parse and format endpoints. Existing Ozone code may use Guava `HostAndPort`, `URI`, +`InetSocketAddress`, or a verified Hadoop/Ozone helper as appropriate for the boundary. The canonical internal host +value does not include brackets. Formatting adds brackets only when a literal is combined with a port or placed in a URI +authority. + +## JVM and listener behavior + +The implementation described by this proposal will stop setting `java.net.preferIPv4Stack=true` by default. Operators +and tests will still be able to set it explicitly when IPv4-only behavior is required. + +Existing listener defaults will remain unchanged. Operators will opt into an IPv6 listener by setting the applicable +bind-host property to an IPv6 address or to `::`. Code must construct listeners from separate host and port values +rather than first constructing an authority string. + +Binding to `::` does not provide the same dual-stack behavior on every operating system. The result depends on the +operating system and its `IPV6_V6ONLY` behavior. The deployment guide will describe this dependency, and the test +environment will verify the address families actually accepted by each listener. Ozone will not treat an IPv6 bind as +proof of IPv4 reachability. + +Bind addresses and advertised addresses are different concepts. Wildcard addresses such as `0.0.0.0` and `::` are +suitable listener values but must not be advertised as peer or client endpoints, Kerberos principals, or certificate +identities. Services will continue to advertise a routable DNS name or unscoped address. Configuration validation will +reject scoped advertised addresses before startup, registration, or publication. + +## Service workstreams + +### Common address utilities + +The common layer will provide and use bracket-aware parsing and formatting for host-only values, endpoints, and URI +authorities. Production endpoint code will be audited for ad hoc colon parsing and host/port concatenation. Non-network +colon-delimited formats will be left unchanged and documented where necessary. + +### SCM and Ratis Review Comment: For SCM and OM HA Ratis groups, yes. The migration must keep the same peer IDs, group IDs, logs, and storage. Stable DNS names make this easier. IPv4 literal addresses require a Ratis configuration update. A change to ozone-site.xml alone is not sufficient. For datanode pipeline groups, NO. SCM replaces pipelines after a datanode address changes. The datanode UUID and container data remain unchanged. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
