Introduce an Istio test harness

dependencies.toml

@@ -49,6 +49,8 @@ hamcrest = "3.0"
 hbase = "1.2.6"
 hibernate-validator6 = "6.2.5.Final"
 hibernate-validator8 = "8.0.3.Final"
+# used by :it:xds-istio
+istio = "1.29.1"
 j2objc = "3.1"
 jackson = "2.21.2"
 jakarta-inject = "2.0.1"
@@ -1409,6 +1411,8 @@ version.ref = "spring-boot4"
 module = "org.testcontainers:testcontainers"
 [libraries.testcontainers-consul]
 module = "org.testcontainers:testcontainers-consul"
+[libraries.testcontainers-k3s]
+module = "org.testcontainers:testcontainers-k3s"
 [libraries.testcontainers-junit-jupiter]
 module = "org.testcontainers:testcontainers-junit-jupiter"
 

it/xds-istio/build.gradle

@@ -0,0 +1,143 @@
+dependencies {
+    implementation project(':junit5')
+    implementation project(':kubernetes')
+    implementation libs.junit5.platform.launcher
+    implementation libs.testcontainers.k3s
+    implementation libs.testcontainers.junit.jupiter
+}
+
+def kubeconfigEnvValue =
+        layout.buildDirectory.file('kubeconfig/kubeconfig.yaml').get().asFile.absolutePath
+def istioVersion = libs.versions.istio.get()
+def istioProfile = 'minimal'
+def istioWorkDir = layout.buildDirectory.dir('istio').get().asFile
+def istioOs = detectIstioOs()
+def istioArch = detectIstioArch()
+def istioSupported = istioOs != null && istioArch != null
+if (!istioSupported) {
+    def osDetector = requireOsDetector()
+    def osValue = osDetector.os
+    def archValue = osDetector.arch
+    logger.warn("Istio is not supported on ${osValue}/${archValue}; skipping :it:xds-istio tasks.")
+    tasks.configureEach {
+        enabled = false
+    }
+    return
+}
+def istioArchive = file("${istioWorkDir}/istio-${istioVersion}-${istioOs}-${istioArch}.tar.gz")
+def istioHomeDir = file("${istioWorkDir}/istio-${istioVersion}")
+def istioctlPath = new File(istioHomeDir, 'bin/istioctl').absolutePath
+def istioEnv = [
+        'KUBECONFIG_PATH': kubeconfigEnvValue,
+        'ISTIO_VERSION': istioVersion,
+        'ISTIO_PROFILE': istioProfile,
+        'ISTIOCTL_PATH': istioctlPath
+]
+
+tasks.register('downloadIstioctl') {
+    outputs.file istioArchive
+    inputs.property 'istioVersion', istioVersion
+    inputs.property 'istioOs', istioOs
+    inputs.property 'istioArch', istioArch
+    doLast {
+        istioArchive.parentFile.mkdirs()
+        def url = "https://github.com/istio/istio/releases/download/${istioVersion}/" +
+                  "istio-${istioVersion}-${istioOs}-${istioArch}.tar.gz"
+        ant.get(src: url, dest: istioArchive, skipexisting: true)
+    }
+}
+
+tasks.register('extractIstioctl', Copy) {
+    dependsOn tasks.named('downloadIstioctl')
+    from tarTree(istioArchive)
+    into istioWorkDir
+    outputs.dir istioHomeDir
+}
+
+tasks.register('prepareIstioctl') {
+    dependsOn tasks.named('extractIstioctl')
+    outputs.file istioctlPath
+    doLast {
+        def istioctlFile = file(istioctlPath)
+        if (!istioctlFile.exists()) {
+            throw new GradleException("istioctl was not found at ${istioctlPath}")
+        }
+        istioctlFile.setExecutable(true)
+    }
+}
+
+def testRuntimeDir = new File(istioWorkDir, 'test-runtime-jars')
+def dockerImagesDir = new File(istioWorkDir, 'docker-images')
+istioEnv['ISTIO_TEST_RUNTIME_DIR'] = testRuntimeDir.absolutePath
+istioEnv['ISTIO_DOCKER_IMAGES_DIR'] = dockerImagesDir.absolutePath
+
+tasks.register('prepareIstioWorkdir') {
+    outputs.dirs testRuntimeDir, dockerImagesDir
+    doLast {
+        testRuntimeDir.mkdirs()
+        dockerImagesDir.mkdirs()
+    }
+}
+
+tasks.register('copyTestRuntimeJars', Sync) {
+    dependsOn tasks.named('prepareIstioWorkdir')
+    from(sourceSets.test.runtimeClasspath)
+    into(testRuntimeDir)
+}
+
+tasks.withType(Test).configureEach {
+    dependsOn tasks.named('copyTestRuntimeJars')
+    dependsOn tasks.named('prepareIstioctl')
+    environment istioEnv
+    systemProperty 'junit.jupiter.execution.parallel.enabled', 'false'
+    maxParallelForks = 1
+    doFirst {
+        def allArgs = (jvmArgs ?: []).join(' ')
+        if (allArgs) {
+            environment 'ISTIO_POD_JVM_ARGS', allArgs
+        }
+    }
+}
+
+// For LocalDevClusterMain
+tasks.withType(JavaExec).configureEach {
+    dependsOn tasks.named('prepareIstioctl')
+    environment istioEnv
+}
+
+def detectIstioOs() {
+    def osDetector = requireOsDetector()
+    def os = osDetector.os
+    if (os == 'osx') {
+        return 'osx'
+    }
+    if (os == 'linux') {
+        return 'linux'
+    }
+    logger.warn("Unsupported OS for Istio: {}", os)
+    return null
+}
+
+def detectIstioArch() {
+    def osDetector = requireOsDetector()
+    def arch = String.valueOf(osDetector.arch).toLowerCase(Locale.ROOT)
+    if (arch == 'x86_64' || arch == 'amd64') {
+        return 'amd64'
+    }
+    if (arch == 'aarch64' || arch == 'arm64' || arch == 'aarch_64' || arch == 'arm_64') {
+        return 'arm64'
+    }
+    if (arch.startsWith('armv7') || arch == 'armv7' || arch == 'arm_32') {
+        return 'armv7'
+    }
+    logger.warn("Unsupported architecture for Istio: {}", arch)
+    return null
+}
+
+def requireOsDetector() {
+    def osDetector = rootProject.extensions.findByName('osdetector')
+    if (osDetector == null) {
+        throw new GradleException("osdetector extension is required for :it:xds-istio")
+    }
+    return osDetector
+}

it/xds-istio/src/main/java/com/linecorp/armeria/it/istio/testing/DockerAvailableCondition.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2025 LY Corporation
+ *
+ * LY Corporation licenses this file to you 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:
+ *
+ *   https://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.
+ */
+package com.linecorp.armeria.it.istio.testing;
+
+import org.junit.jupiter.api.extension.ConditionEvaluationResult;
+import org.junit.jupiter.api.extension.ExecutionCondition;
+import org.junit.jupiter.api.extension.ExtensionContext;
+import org.testcontainers.DockerClientFactory;
+
+final class DockerAvailableCondition implements ExecutionCondition {
+    @Override
+    public ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext context) {
+        // When running inside a K8s pod, Docker is not available but the test should still run.
+        if (HostOnlyExtension.isRunningInPod()) {
+            return ConditionEvaluationResult.enabled("Running inside K8s pod");
+        }
+        final boolean available = DockerClientFactory.instance().isDockerAvailable();
+        return available ?
+               ConditionEvaluationResult.enabled("Docker is available")
+               : ConditionEvaluationResult.disabled("Docker daemon is not running");
+    }
+}

it/xds-istio/src/main/java/com/linecorp/armeria/it/istio/testing/EnabledIfDockerAvailable.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2025 LY Corporation
+ *
+ * LY Corporation licenses this file to you 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:
+ *
+ *   https://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.
+ */
+package com.linecorp.armeria.it.istio.testing;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.junit.jupiter.api.extension.ExtendWith;
+
+/**
+ * Enables the annotated test class or method only when the Docker daemon is available,
+ * or when running inside a Kubernetes pod (where Docker is not needed).
+ */
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@ExtendWith(DockerAvailableCondition.class)
+public @interface EnabledIfDockerAvailable {}

it/xds-istio/src/main/java/com/linecorp/armeria/it/istio/testing/HostOnlyExtension.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2025 LY Corporation
+ *
+ * LY Corporation licenses this file to you 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:
+ *
+ *   https://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.
+ */
+package com.linecorp.armeria.it.istio.testing;
+
+import org.junit.jupiter.api.extension.ExtensionContext;
+
+import com.linecorp.armeria.testing.junit5.common.AbstractAllOrEachExtension;
+
+/**
+ * Base class for JUnit extensions that must only run when executing on the host,
+ * not inside a Kubernetes pod. Subclass this instead of {@link AbstractAllOrEachExtension}
+ * when the extension manages host-side infrastructure (cluster lifecycle, container
+ * management, etc.) that must not execute inside the in-cluster test job.
+ *
+ * <p>Implement {@link #setUp} and optionally {@link #tearDown}. Both are no-ops
+ * when {@code RUNNING_IN_K8S_POD=true}.
+ */
+abstract class HostOnlyExtension extends AbstractAllOrEachExtension {
+
+    static final String RUNNING_IN_K8S_POD_ENV = "RUNNING_IN_K8S_POD";
+
+    static boolean isRunningInPod() {
+        return Boolean.parseBoolean(System.getenv(RUNNING_IN_K8S_POD_ENV));
+    }
+
+    static boolean notRunningInPod() {
+        return !isRunningInPod();
+    }
+
+    @Override
+    protected final void before(ExtensionContext context) throws Exception {
+        if (notRunningInPod()) {
+            setUp(context);
+        }
+    }
+
+    @Override
+    protected final void after(ExtensionContext context) throws Exception {
+        if (notRunningInPod()) {
+            tearDown(context);
+        }
+    }
+
+    abstract void setUp(ExtensionContext context) throws Exception;
+
+    void tearDown(ExtensionContext context) throws Exception {}
+}