smengcl commented on code in PR #10981: URL: https://github.com/apache/ozone/pull/10981#discussion_r3755709491
########## 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. Review Comment: Yes, migrating an existing cluster should be possible. However, it first needs be upgraded to an IPv6-capable Ozone release with non-rolling upgrade, which requires a maintenance window. This proposal does not guarantee a zero-downtime migration. `hdds.datanode.use.datanode.hostname=true` can simplify a dual-stack transition by using stable DNS names for datanode connections, but it is not an identity or IPv6 requirement. A datanode is identified by its persisted UUID. When it re-registers with a changed address, SCM updates the existing datanode and rebuilds affected pipelines. Updated doc to reflect that. -- 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]
