feat: Kube API Test

CHANGELOG.md

@@ -16,6 +16,7 @@
 
 #### New Features
 * Fix #5636: Add new extension `open-virtual-networking` to manage resources in `k8s.ovn.org/v1` API group.
+* Fix #5711: Kube API Test - Kubernetes API Server JUnit Test Support
 
 #### _**Note**_: Breaking changes
 

README.md

@@ -399,6 +399,26 @@ class ExampleTest {
     }
 }
 ```
+
+## Testing Against real Kubernetes API Server with Kube API Test
+
+In order to test against real Kubernetes API the project provides a lightweight approach, thus starting up Kubernetes API Server and etcd binaries.
+
+```java
+@EnableKubeAPIServer
+class KubeAPITestSample {
+
+  static KubernetesClient client;
+
+  @Test
+  void testWithClient() {
+    // test using the client against real K8S API Server   
+  }
+}
+```
+
+For details see docs for [Kube API Test](doc/kube-api-test.md).
+
 ## Compatibility
 
 ### Kubernetes

doc/kube-api-test.md

@@ -0,0 +1,153 @@
+# kube-api-test
+
+`kube-api-test` makes it easy to implement integration tests with Kubernetes API Server in Java.
+Inspired by [envtest](https://book.kubebuilder.io/reference/envtest.html) in Kubebuilder (Golang).
+
+It runs the API Server binaries directly (without nodes and other components, but with etcd).
+Linux, Windows, Mac is supported.
+
+## Usage
+
+Include dependency:
+
+```xml
+<dependency>
+    <groupId>io.fabric8</groupId>
+    <artifactId>kube-api-test</artifactId>
+    <version>[version]</version>
+    <scope>test</scope>
+</dependency>
+```
+
+### In Unit Tests
+
+See sample unit
+test [here](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/core/src/test/java/io/fabric8/kubeapitest/sample/JUnitExtensionSimpleCaseTest.java)
+
+```java
+
+@EnableKubeAPIServer
+class JUnitExtensionSimpleCaseTest {
+
+    // Use @KubeConfig annotation to inject kube config yaml to init any client
+    @KubeConfig
+    static String kubeConfigYaml;
+
+    @Test
+    void simpleTestWithTargetVersion() {
+        var client = new KubernetesClientBuilder()
+                .withConfig(Config.fromKubeconfig(kubeConfigYaml))
+                .build();
+
+        client.resource(TestUtils.testConfigMap()).create();
+        var cm = client.resource(TestUtils.testConfigMap()).get();
+
+        Assertions.assertThat(cm).isNotNull();
+    }
+}
+```
+
+### Public API
+
+The underlying API can be used directly.
+See [KubeApiServer](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/core/src/main/java/io/fabric8/kubeapitest/KubeAPIServer.java#L28-L28)
+
+See
+it's [usage in a test](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/core/src/test/java/io/fabric8/kubeapitest/sample/KubeApiServerTest.java#L31-L31).
+
+```java
+class KubeApiServerTest {
+
+    @Test
+    void apiServerTest() {
+        var kubeApi = new KubeAPIServer();
+        kubeApi.start();
+
+        var client =  new KubernetesClientBuilder()
+                .withConfig(Config.fromKubeconfig(kubeApi.getKubeConfigYaml()))
+                .build();
+
+        client.resource(TestUtils.testConfigMap()).create();
+
+        var cm = client.resource(TestUtils.testConfigMap()).get();
+        Assertions.assertThat(cm).isNotNull();
+
+        kubeApi.stop();
+    }
+}
+```
+
+### Fabric8 Client Injection Support
+
+Use dependency:
+
+```xml
+<dependency>
+    <groupId>io.fabric8</groupId>
+    <artifactId>kube-api-test-client-inject</artifactId>
+    <version>[version]</version>
+    <scope>test</scope>
+</dependency>
+```
+
+The client can be directly injected to the test. See sample test [here](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/client-inject/src/test/java/io/fabric8/kubeapitest/junit/sample/JUnitFabric8ClientInjectionTest.java#L28-L28).
+
+```java
+
+@EnableKubeAPIServer
+class JUnitFabric8ClientInjectionTest {
+
+    static KubernetesClient client;
+
+    // emitted code     
+}  
+```
+
+### Configuration Options
+
+See available configuration options documented in [KubeAPIServerConfig](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/core/src/main/java/io/fabric8/kubeapitest/KubeAPIServerConfig.java)
+
+Not all those properties can be overridden using [`@EnableKubeAPIServer`](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/core/src/main/java/io/fabric8/kubeapitest/junit/EnableKubeAPIServer.java)
+annotation, since might not make sense to do it for an individual test case. However, those can be passed to
+[`KubeApiServer`](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/core/src/main/java/io/fabric8/kubeapitest/KubeAPIServer.java)
+and also configured globally using environment variables, see [KubeAPIServerConfigBuilder](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/core/src/main/java/io/fabric8/kubeapitest/KubeAPIServerConfigBuilder.java)
+
+
+### Updating kube config file
+
+In general, it is not advised but if instructed kube config file (~/kube/config) is updated by the framework.
+See related property in [`@EnableKubeAPIServer`](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/core/src/main/java/io/fabric8/kubeapitest/junit/EnableKubeAPIServer.java#L42-L42)
+annotation. The config file is automatically cleaned up on stop.
+
+### How does it work
+
+In the background Kubernetes and etcd (and kubectl) binaries are downloaded if not found locally.
+All the certificates for the Kube API Server and for the client is generated.
+The client certificates are generated with group `system:masters`;
+
+### Downloading binaries
+
+Binaries are downloaded automatically under ~/.kubeapitest/k8s/[target-platform-and-version] if no binary found locally.
+If there are multiple binaries found, the latest if selected (unless a target version is not specified).
+
+Also [`setup-envtest`](https://pkg.go.dev/sigs.k8s.io/controller-runtime/tools/setup-envtest#section-readme) can be used
+to download binaries manually. By executing `setup-envtest use --bin-dir ~/.kubeapitest` will download the latest required
+binaries to the default directory. This is useful if always running the tests in offline mode.
+
+### Support for Parallel Execution in Junit5
+
+Parallel test execution is explicitly supported for JUnit5, in fact the project tests are running parallel.
+Running a new instance for each test case. This speeds up the tests (in our case >75%) in a way that test cases are also
+fully isolated from each other. Although we experienced stability issues on non-Linux platforms. 
+
+### Testing Mutation and Validation Webhooks
+
+An additional benefit of running K8S API Server this way, is that it makes easy to test
+[Conversion Hooks](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#webhook-conversion)
+and/or
+[Dynamic Admission Controllers](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)
+
+In general, it is a best practice to use additional standard frameworks to implement Kubernetes webhooks,
+like [kubernetes-webooks-framework](https://github.com/java-operator-sdk/kubernetes-webooks-framework)
+with Quarkus or Spring. However, we demonstrate how it works
+in [this test](https://github.com/fabric8io/kubernetes-client/blob/main/junit/kube-api-test/core/src/test/java/io/fabric8/kubeapitest/sample/KubernetesMutationHookHandlingTest.java#L72-L72)

junit/kube-api-test/client-inject/pom.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (C) 2015 Red Hat, Inc.
+
+    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.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+      <groupId>io.fabric8</groupId>
+      <artifactId>kube-api-test-parent</artifactId>
+      <version>6.11-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>kube-api-test-client-inject</artifactId>
+    <packaging>jar</packaging>
+    <name>Kube API Test - Client Injecting Support</name>
+
+    <dependencies>
+        <dependency>
+          <groupId>io.fabric8</groupId>
+          <artifactId>kube-api-test</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>compile</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>compile</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.fabric8</groupId>
+            <artifactId>kubernetes-client</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.logging.log4j</groupId>
+            <artifactId>log4j-slf4j2-impl</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.logging.log4j</groupId>
+            <artifactId>log4j-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

junit/kube-api-test/client-inject/src/main/java/io/fabric8/kubeapitest/junit/Fabric8ClientInjectionHandler.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright (C) 2015 Red Hat, Inc.
+ *
+ * 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.
+ */
+package io.fabric8.kubeapitest.junit;
+
+import io.fabric8.kubeapitest.KubeAPIServer;
+import io.fabric8.kubeapitest.KubeAPITestException;
+import io.fabric8.kubernetes.client.Config;
+import io.fabric8.kubernetes.client.KubernetesClient;
+import io.fabric8.kubernetes.client.KubernetesClientBuilder;
+import org.junit.jupiter.api.extension.ExtensionContext;
+
+import java.lang.reflect.Field;
+import java.util.Arrays;
+import java.util.Optional;
+import java.util.stream.Collectors;
+
+public class Fabric8ClientInjectionHandler implements ClientInjectionHandler {
+
+  private KubernetesClient client;
+
+  public boolean isTargetFieldAvailable(ExtensionContext extensionContext,
+      boolean staticField) {
+    return getFieldForKubeClientInjection(extensionContext, staticField).isPresent();
+  }
+
+  @Override
+  public void inject(ExtensionContext extensionContext,
+      boolean staticField, KubeAPIServer kubeApiServer) {
+    var field = getFieldForKubeClientInjection(extensionContext, staticField).orElseThrow();
+    setKubernetesClientToField(extensionContext, field, kubeApiServer);
+  }
+
+  private void setKubernetesClientToField(ExtensionContext extensionContext,
+      Field kubeClientField, KubeAPIServer kubeApiServer) {
+    try {
+      var target = extensionContext.getTestInstance()
+          .orElseGet(() -> extensionContext.getTestClass().orElseThrow());
+      client = new KubernetesClientBuilder()
+          .withConfig(Config.fromKubeconfig(kubeApiServer.getKubeConfigYaml())).build();
+      kubeClientField.setAccessible(true);
+      kubeClientField.set(target, client);
+    } catch (IllegalAccessException e) {
+      throw new KubeAPITestException(e);
+    }
+  }
+
+  @Override
+  public void cleanup(ExtensionContext extensionContext) {
+    if (client != null) {
+      client.close();
+    }
+  }
+
+  public static Optional<Field> getFieldForKubeClientInjection(ExtensionContext extensionContext,
+      boolean staticField) {
+    Class<?> clazz = extensionContext.getTestClass().orElseThrow();
+    var kubeConfigFields = Arrays.stream(clazz.getDeclaredFields())
+        .filter(f -> KubernetesClient.class.isAssignableFrom(f.getType()))
+        .collect(Collectors.toList());
+    if (kubeConfigFields.isEmpty()) {
+      return Optional.empty();
+    }
+    if (kubeConfigFields.size() > 1) {
+      throw new KubeAPITestException(
+          "More fields type KubernetesClient found");
+    }
+    var field = kubeConfigFields.get(0);
+    if (java.lang.reflect.Modifier.isStatic(field.getModifiers()) != staticField) {
+      return Optional.empty();
+    } else {
+      return Optional.of(field);
+    }
+  }
+}

junit/kube-api-test/client-inject/src/main/resources/META-INF/services/io.fabric8.kubeapitest.junit.ClientInjectionHandler

@@ -0,0 +1 @@
+io.fabric8.kubeapitest.junit.Fabric8ClientInjectionHandler