feat(hdfs): add support for localHdfsSitePath configuration

- Introduced `localHdfsSitePath` to enable writing host-side Hadoop XML files with HDFS client properties.
- Updated `BigDataContainerFactory` to generate and manage `hdfs-site.xml` files dynamically.
- Enhanced Gradle plugin and test framework to integrate the new configuration option.
- Updated user documentation to explain the usage and behavior of `localHdfsSitePath`.

Author: CoderYellow

core/src/main/kotlin/org/openprojectx/bigdata/test/core/BigDataTestKitOptions.kt

@@ -70,6 +70,7 @@ data class HdfsOptions(
     val nameNodePort: Int = 8020,
     val dataNodePort: Int = 9866,
     val dataNodeHostname: String = "hdfs",
+    val localHdfsSitePath: String? = null,
     val webPort: Int = 9870,
     val webTls: HttpTlsOptions = HttpTlsOptions(),
     val kerberos: KerberosAuthOptions = KerberosAuthOptions(

core/src/main/kotlin/org/openprojectx/bigdata/test/core/config/BigDataTestConfig.kt

@@ -70,9 +70,13 @@ data class BigDataTestConfig(
 
 data class BigDataTestHdfsConfig(
     val dataNodeHostname: String? = null,
+    val localHdfsSitePath: String? = null,
 ) {
     fun merge(override: BigDataTestHdfsConfig): BigDataTestHdfsConfig =
-        BigDataTestHdfsConfig(dataNodeHostname = override.dataNodeHostname ?: dataNodeHostname)
+        BigDataTestHdfsConfig(
+            dataNodeHostname = override.dataNodeHostname ?: dataNodeHostname,
+            localHdfsSitePath = override.localHdfsSitePath ?: localHdfsSitePath,
+        )
 }
 
 data class BigDataTestHiveMetastoreConfig(
@@ -361,7 +365,10 @@ class BigDataTestConfigLoader(
                 trustStorePassword = tls.string("trustStorePassword"),
                 haproxyImage = tls.string("haproxyImage"),
             ),
-            hdfs = BigDataTestHdfsConfig(dataNodeHostname = hdfs.string("dataNodeHostname")),
+            hdfs = BigDataTestHdfsConfig(
+                dataNodeHostname = hdfs.string("dataNodeHostname"),
+                localHdfsSitePath = hdfs.string("localHdfsSitePath"),
+            ),
             hiveMetastore = BigDataTestHiveMetastoreConfig(
                 databaseName = hiveMetastore.string("databaseName"),
                 databaseUser = hiveMetastore.string("databaseUser"),

core/src/main/kotlin/org/openprojectx/bigdata/test/core/container/BigDataContainerFactory.kt

@@ -49,6 +49,13 @@ internal class BigDataContainerFactory(
         } else {
             null
         }
+    private val hdfsClientDir: Path by lazy {
+        options.hdfs.localHdfsSitePath
+            ?.let { Path.of(it).parent }
+            ?.let { Files.createDirectories(it) }
+            ?: kerberosDir
+            ?: Files.createTempDirectory("bigdata-test-hdfs-client-")
+    }
     private val tlsMaterial: TlsMaterial by lazy { TlsMaterial(options.tls.copy(enabled = true)) }
 
     fun healthCheck(service: BigDataService, container: GenericContainer<*>, endpoint: BigDataEndpoint) {
@@ -198,6 +205,13 @@ internal class BigDataContainerFactory(
                 backendPort = hdfs.webPort,
                 hostPort = tlsHostPort(options.portBindings.hdfsWebTls),
             )
+            val clientProperties = mapOf(
+                "fs.defaultFS" to "hdfs://$nameNode",
+                "dfs.client.use.datanode.hostname" to "true",
+                "dfs.datanode.hostname" to hdfs.dataNodeHostname,
+            ) + hdfsKerberosClientProperties(hdfs.kerberos) +
+                webTls.property("dfs.namenode.https-address")
+            val localHdfsSite = writeLocalHdfsSiteXml(hdfs, clientProperties)
             BigDataEndpoint(
                 service = BigDataService.HDFS,
                 host = container.host,
@@ -207,12 +221,10 @@ internal class BigDataContainerFactory(
                     "web" to container.getMappedPort(hdfs.webPort),
                 ) + webTls.port("web-tls"),
                 properties = mapOf(
-                    "fs.defaultFS" to "hdfs://$nameNode",
                     "spring.hadoop.fs-uri" to "hdfs://$nameNode",
-                    "dfs.client.use.datanode.hostname" to "true",
-                    "dfs.datanode.hostname" to hdfs.dataNodeHostname,
-                ) + hdfsKerberosClientProperties(hdfs.kerberos) +
-                    webTls.property("dfs.namenode.https-address") +
+                    "bigdata.test.hdfs.hdfs-site" to localHdfsSite,
+                    "bigdata.test.hdfs.hdfs-site.container" to "/opt/hadoop/etc/hadoop/hdfs-site.xml",
+                ) + clientProperties +
                     webTls.jvmProperties() +
                     kerberosProperties("hadoop", hdfs.kerberos),
             )
@@ -743,6 +755,7 @@ internal class BigDataContainerFactory(
     }
 
     private fun writeConfigurationXml(path: Path, properties: Map<String, String>) {
+        path.parent?.let { Files.createDirectories(it) }
         Files.writeString(path, configurationXml(properties), StandardCharsets.UTF_8)
     }
 
@@ -1165,6 +1178,14 @@ internal class BigDataContainerFactory(
             emptyMap()
         }
 
+    private fun writeLocalHdfsSiteXml(hdfs: HdfsOptions, properties: Map<String, String>): String {
+        val path = hdfs.localHdfsSitePath
+            ?.let { Path.of(it) }
+            ?: hdfsClientDir.resolve("hdfs-site.xml")
+        writeConfigurationXml(path, properties)
+        return path.toString()
+    }
+
     private fun hdfsSiteSecurity(kerberos: KerberosAuthOptions): String =
         if (kerberos.enabled) {
             """

doc/user-guide.adoc

@@ -290,13 +290,16 @@ HDFS-specific startup settings use the `[hdfs]` table. Keep the default `dataNod
 ----
 [hdfs]
 dataNodeHostname = "localhost"
+localHdfsSitePath = "build/bigdata-test/hadoop/hdfs-site.xml"
 
 [ports]
 hdfsNameNode = 8020
 hdfsDataNode = 9866
 hdfsWeb = 9870
 ----
 
+`localHdfsSitePath` is optional. When set, the framework writes a host-side Hadoop XML file with the resolved HDFS client properties, including the mapped NameNode URI, DataNode hostname mode, and Kerberos client settings when HDFS Kerberos is enabled. When omitted, the file is generated in framework-managed temporary material.
+
 === Container Customization Escape Hatch
 
 Typed service options should cover the normal path, but integration-test containers sometimes need image-specific workarounds before the framework has first-class support. Use container customizations as an escape hatch for troubleshooting or temporary overrides.
@@ -1484,6 +1487,7 @@ bigDataTest {
     hdfs {
         kerberosEnabled.set(true)
         dataNodeHostname.set("localhost")
+        localHdfsSitePath.set("build/bigdata-test/hadoop/hdfs-site.xml")
     }
     ports {
         hdfsNameNode.set(8020)
@@ -1614,11 +1618,14 @@ The plugin injects raw endpoint properties, such as `fs.defaultFS`, `hive.metast
 [source,text]
 ----
 bigdata.test.endpoint.hdfs.properties.fs.defaultFS
+bigdata.test.endpoint.hdfs.properties.bigdata.test.hdfs.hdfs-site
 bigdata.test.endpoint.hdfs.ports.namenode
 bigdata.test.endpoint.localstack-s3.properties.aws.endpoint-url.s3
 bigdata.test.extensions.s3-jceks.credential-provider.path
 ----
 
+For HDFS clients that prefer Hadoop XML resources, read `bigdata.test.endpoint.hdfs.properties.bigdata.test.hdfs.hdfs-site` and add that file to the Hadoop `Configuration`. The Gradle plugin also injects the same value as an environment variable for launched tasks.
+
 Environment variable names are generated by uppercasing property keys and replacing non-alphanumeric characters with `_`:
 
 [source,text]

example/spring-gradle-plugin/src/main/resources/spring-bigdata-test.toml

@@ -13,6 +13,7 @@ debug = true
 
 [hdfs]
 dataNodeHostname = "localhost"
+localHdfsSitePath = "build/bigdata-test/hadoop/hdfs-site.xml"
 
 [ports]
 hdfsNameNode = 8020

gradle-plugin/src/main/kotlin/org/openprojectx/bigdata/test/gradle/BigDataTestGradleExtension.kt

@@ -157,6 +157,7 @@ abstract class BigDataTestGradleHdfs @Inject constructor(objects: ObjectFactory)
     val image: Property<String> = objects.property(String::class.java).convention("apache/hadoop:3.5.0")
     val kerberosEnabled: Property<Boolean> = objects.property(Boolean::class.java).convention(false)
     val dataNodeHostname: Property<String> = objects.property(String::class.java).convention("hdfs")
+    val localHdfsSitePath: Property<String> = objects.property(String::class.java).convention("")
 }
 
 abstract class BigDataTestGradleHiveMetastore @Inject constructor(objects: ObjectFactory) {

gradle-plugin/src/main/kotlin/org/openprojectx/bigdata/test/gradle/BigDataTestGradlePlugin.kt

@@ -93,6 +93,7 @@ class BigDataTestGradlePlugin : Plugin<Project> {
             spec.parameters.hdfsImage.set(extension.hdfs.image)
             spec.parameters.hdfsKerberosEnabled.set(extension.hdfs.kerberosEnabled)
             spec.parameters.hdfsDataNodeHostname.set(extension.hdfs.dataNodeHostname)
+            spec.parameters.hdfsLocalHdfsSitePath.set(extension.hdfs.localHdfsSitePath)
 
             spec.parameters.hiveMetastoreImage.set(extension.hiveMetastore.image)
             spec.parameters.hiveMetastoreDatabaseImage.set(extension.hiveMetastore.databaseImage)
@@ -307,6 +308,7 @@ class BigDataTestGradlePlugin : Plugin<Project> {
         extension.tls.haproxyImage.tomlConvention(config.tls.haproxyImage)
 
         extension.hdfs.dataNodeHostname.tomlConvention(config.hdfs.dataNodeHostname)
+        extension.hdfs.localHdfsSitePath.tomlConvention(config.hdfs.localHdfsSitePath)
         extension.hiveMetastore.databaseName.tomlConvention(config.hiveMetastore.databaseName)
         extension.hiveMetastore.databaseUser.tomlConvention(config.hiveMetastore.databaseUser)
         extension.hiveMetastore.databasePassword.tomlConvention(config.hiveMetastore.databasePassword)

gradle-plugin/src/main/kotlin/org/openprojectx/bigdata/test/gradle/BigDataTestGradleService.kt

@@ -85,6 +85,7 @@ abstract class BigDataTestGradleService : BuildService<BigDataTestGradleService.
         val hdfsImage: Property<String>
         val hdfsKerberosEnabled: Property<Boolean>
         val hdfsDataNodeHostname: Property<String>
+        val hdfsLocalHdfsSitePath: Property<String>
 
         val hiveMetastoreImage: Property<String>
         val hiveMetastoreDatabaseImage: Property<String>
@@ -205,6 +206,7 @@ abstract class BigDataTestGradleService : BuildService<BigDataTestGradleService.
                     enabled = true,
                     image = parameters.hdfsImage.get(),
                     dataNodeHostname = parameters.hdfsDataNodeHostname.get(),
+                    localHdfsSitePath = projectPath(parameters.hdfsLocalHdfsSitePath.get()),
                     kerberos = KerberosAuthOptions(
                         enabled = parameters.hdfsKerberosEnabled.get(),
                         servicePrincipal = "nn/hdfs.${parameters.kerberosDomain.get()}@${parameters.kerberosRealm.get()}",