Copilot commented on code in PR #10981: URL: https://github.com/apache/ozone/pull/10981#discussion_r3747178800
########## hadoop-hdds/docs/content/design/ipv6-support.md: ########## @@ -0,0 +1,342 @@ +--- +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. +- Support link-local or scoped IPv6 addresses as persistent cluster identities. Scope identifiers are interface-local + and are not valid 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. +- **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 + +Ozone no longer sets `java.net.preferIPv4Stack=true` by default. Operators and tests can still set it explicitly when +IPv4-only behavior is required. Review Comment: This design doc reads like the behavior change is already implemented (“Ozone no longer sets ...”), but this PR is an OEP draft. Using future/intent language here avoids misleading readers about current defaults. -- 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]
