fabric8io Kubernetes Client

The chaos tests simulate network disruptions to ensure SharedInformers recover appropriately. The test flow involves two main components:

• Checker: A Pod running a SharedInformer on a specific ConfigMap. It waits for a counter in that ConfigMap to reach a target value N.
• Control: A Pod that increments the counter in the ConfigMap up to the target value N.

The Experiment:

1. The Checker and Control applications start.
2. A Chaos Experiment (using 3 different network disruption scenarios) is launched targeting the Checker app.
3. The experiment runs for 12 minutes.
4. Success Criteria: After the experiment, the Checker's SharedInformer must recover, reach the target value N, and both the Control and Checker Pods must reach a Successful state.

The Fabric8 Kubernetes Client is undergoing research for a non-blocking API to support callers with non-blocking dispatchers (such as event loops or reactive pipelines).

Key Design Principles:

• Return Types: The preferred public return type for asynchronous operations is CompletionStage<T> rather than CompletableFuture<T>.
• Usage Recommendation: If you are using Java 21+ with a virtual thread executor and simply need concurrent simple calls, it is recommended to continue using the existing blocking API. The async surface is specifically intended for reactive/non-blocking environments.
• Current Limitations: The async API is considered "best-effort" until certain blocking components (like the OIDC interceptor) are addressed.

Most public terminal methods in the Kubernetes Client DSL (e.g., get(), list(), create(), patch()) are synchronous and blocking. This is because they funnel through OperationSupport.waitForResult, which calls future.get() on an internal CompletableFuture.

While the underlying HTTP backends (JDK, OkHttp, Jetty, and Vert.x) are natively asynchronous, the high-level DSL is designed to be blocking for ease of use. If you require non-blocking behavior, you must look for specific async-shaped methods or use alternative patterns like Virtual Threads.

The CRD Generator v2 is the current recommended way to generate Kubernetes Custom Resource Definitions (CRDs) from Java classes. It is based on Jackson/jsonSchema and consists of several modules depending on your build environment or execution method.

Available modules for v2:

• CRD Generator API v2 (io.fabric8:crd-generator-api-v2): The core implementation.
• CRD Generator Collector (io.fabric8:crd-generator-collector): Used to find and load compiled Custom Resource classes from directories and Jar files.
• CRD Generator Maven Plugin (io.fabric8:crd-generator-maven-plugin): For automatic generation during the Maven build process.
• CRD Generator CLI (io.fabric8:crd-generator-cli): A standalone command-line tool for manual generation.

You can install the CRD-Generator CLI by downloading the shell script from Sonatype or by using jbang.

To download and install the latest version via shell script:

1. Fetch the latest version tag from GitHub.
2. Download the .sh file from Sonatype.
3. Make the file executable.

Alternatively, if you have jbang installed, you can run the CLI directly without a manual installation.

# Download and install via shell script
export VERSION=$(wget -q -O - https://github.com/fabric8io/kubernetes-client/releases/latest --header "Accept: application/json" | jq -r '.tag_name' | cut -c 2-)
wget -O crd-gen https://oss.sonatype.org/content/repositories/releases/io/fabric8/crd-generator-cli/$VERSION/crd-generator-cli-$VERSION.sh
chmod a+x crd-gen
./crd-gen --version

# Or run via jbang
jbang io.fabric8:crd-generator-cli:<version>

The plugin uses Jandex to find Custom Resource classes. A class is identified if it:

1. Implements the HasMetadata interface (the abstract class CustomResource implements this).
2. Is annotated with both @Group and @Version.

Important: If your Custom Resource extends a custom abstract class or interface that indirectly implements HasMetadata, ensure that intermediate class is included in the scan/index.

To improve performance, the plugin will use existing serialized Jandex indices found in the project or dependencies. To force a new index creation, set forceIndex to true.

To use the Java generator in Gradle, apply the io.fabric8.java-generator plugin. Use the javaGen closure to specify the source directory. If using extraAnnotations, you must explicitly configure annotationProcessor and compileOnly dependencies for builder-annotations and lombok. You can trigger the generation using the crd2Java task.

plugins {
  id 'io.fabric8.java-generator' version "${kubernetesClientVersion}"
}

dependencies {
  // extraAnnotations requires explicit annotation processor configuration
  annotationProcessor "io.sundr:builder-annotations:${sundrioVersion}"
  compileOnly         "io.sundr:builder-annotations:${sundrioVersion}"
  compileOnly         "org.projectlombok:lombok:${lombokVersion}"
}

javaGen {
  source = file('src/main/resources/kubernetes')
}

// Run via command line:
// gradle crd2Java

Depending on your needs, you can choose between two dependency patterns:

1. Full Client: Use kubernetes-client or openshift-client as compile dependencies. This is required if you use internal classes.
2. API-only Compile Time: Use kubernetes-client-api or openshift-client-api for compile dependencies, and kubernetes-client or openshift-client as a runtime dependency. This provides a cleaner compile-time classpath.

HttpClient Selection: By default, the client uses Vert.x (kubernetes-httpclient-vertx). To use a different implementation (like OkHttp), exclude kubernetes-httpclient-vertx and include your preferred runtime dependency.