How to use Fabric8 Java Client with Kubernetes

The last few years have seen a rise in containers-based development, with more programmers coming to understand the benefits of using containers rather than traditional VMs or just bare metal. Kubernetes arose to help scale containers for enterprise use cases and has established itself as the most popular container orchestrating platform. From the beginning of the Kubernetes project, the community of users and contributors has grown fast. As of this publication, it is one of the most popular projects on Github.

I recently read the book Programming Kubernetes, which gives an overview of programming Kubernetes with Golang. As a contributor to the Fabric8 Kubernetes Client, I was inspired to write a blog series that covers similar topics from a Java developer's perspective.

Red Hat Developer has presented Fabric8 Java Client before in several articles, including:

• Getting started with the Fabric8 Kubernetes Java client
• What's new in Fabric8 Kubernetes client version 5.5.0
• New HTTP clients, a Java generator, and more in Fabric8 6.0.0

This article is the first installment in my series focusing on topics from a developer's perspective.

• Part 1: How to use Fabric8 Java Client with Kubernetes
• Part 2: Programming Kubernetes custom resources in Java
• Part 3: How to use Kubernetes dynamic client with Fabric8
• Part 4: How to generate code using Fabric8 Kubernetes Client
• Part 5: How to write tests with Fabric8 Kubernetes Client

Why program Kubernetes in Java?

Kubernetes is written in Golang, as are most of the tools and libraries built around it. So why would it be a good idea to program Kubernetes in a language like Java?

Well, if you don't have a Golang background, it would take some time to learn the language—an effort that might be unnecessary if you don't plan to use Golang elsewhere in your organization.

Kubernetes exposes most of its operations via its REST API. Even a tool like kubectl contacts the Kubernetes Server API via its REST API. You can see this by checking kubectl verbose logs:

~ : $ kubectl get pods -v=6

I0716 15:32:51.736643    8647 loader.go:372] Config loaded from file:  /home/rokumar/.kube/config

I0716 15:32:51.746201    8647 round_trippers.go:454] GET https://[::1]:37775/api/v1/namespaces/default/pods?limit=500 200 OK in 6 milliseconds

NAME                                     READY   STATUS    RESTARTS   AGE

nginx-deploymentwt9x9-5d59d67564-dlndq   1/1     Running   3          19h

nginx-deploymentwt9x9-5d59d67564-pjm97   1/1     Running   3          19h

nginx-deploymentwt9x9-5d59d67564-qsfp7   1/1     Running   3          19h

At the time of this article, Kubernetes 1.25 is the latest stable release. Read the Kubernetes API reference document for more information. You can interact with the REST API with any programming language. Java is still one of the most popular programming languages, and many companies still use it.

Currently, there are multiple Java libraries for Kubernetes, the most popular being the Fabric8 Kubernetes Client and the Official Kubernetes client. We will focus on Fabric8 because it provides a fluent DSL for interacting with the Kubernetes API, a mock testing framework for writing Kubernetes Java tests, and extension hooks to create your KubernetesClient extensions.

Fabric8 Kubernetes Client provides excellent support for interacting with Kubernetes programmatically via Java. In this series, we will develop Java applications that interact with Kubernetes APIs to perform an operation.

How to Obtain Fabric8 Kubernetes Client

The Fabric8 Kubernetes Client library should be available on Maven Central. If you are using Maven, you should be able to add it as a dependency in your project by adding the following to the dependencies section of your pom.xml file:

<dependency>
  <groupId>io.fabric8</groupId>
  <artifactId>kubernetes-client</artifactId>
  <version>6.1.1</version>
</dependency>

Gradle users should add this line to build.gradle:

implementation 'io.fabric8:kubernetes-client:6.1.1'

How to use the Fabric8 Kubernetes Client

Once you have added the kubernetes-client dependency to your project, you can start using it.

First, initialize a KubernetesClient object:

try (KubernetesClient client = new KubernetesClientBuilder().build()) {

}

This would automatically create an opinionated KubernetesClient object by reading configuration either from the local ~/.kube/config file or from the currently mounted ServiceAccount (in case it's inside a pod).

It's also possible to provide your own configuration to the client:

try (KubernetesClient client = new KubernetesClientBuilder()
    .withConfig(new ConfigBuilder()
        .withMasterUrl("https://api.sandbox.x8i5.example.com:6443")
        .withOauthToken("sha256~secret")
        .withNamespace("default")
        .withCaCertFile("/home/foo/.minikube/ca.crt")
        .withClientCertFile("/home/foo/.minikube/profiles/minikube/client.crt")
        .withClientKeyFile("/home/foo/.minikube/profiles/minikube/client.key")
        .withClientKeyAlgo("RSA")
        .build())
    .build()) {

}

Another option is to configure Fabric8 Kubernetes Client using properties. Table 1 lists properties you can use to tune the client's behavior.

You can read the complete list of properties in the Fabric8 Kubernetes Client documentation.

Create, read, update, and delete operations with Fabric8 Kubernetes Client

Fabric8 Kubernetes Client provides a fluent DSL, so it is easy to do basic create, read, update, and delete (CRUD) operations on built-in resources.

Here's an example:

try (KubernetesClient client = new KubernetesClientBuilder().build()) {
  // Load the Service resource definition from a file
  Service svc = client.services()
      .load(CreateReadUpdateDeleteDemo.class.getResourceAsStream("/test-svc.yaml"))
      .get();

  // Create a Service
  client.services()
      .inNamespace("default")
      .resource(svc)
      .create();

  // List Services
  ServiceList svcList = client.services().inNamespace("default").list();
  logger.info("Found {} Services", svcList.getItems().size());


  // Update Service
  svc.getMetadata().setLabels(Collections.singletonMap("foo", "bar"));
  client.services()
      .inNamespace("default")
      .resource(svc)
      .replace();

  // Delete Service
  client.services()
      .inNamespace("default")
      .resource(svc)
      .delete();
}

Create objects using builders

Fabric8 Kubernetes Client also provides fluent builders for Kubernetes resource objects so that you can create these complex objects inline.

Consider a scenario in which you have this Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9
        ports:
        - containerPort: 80

You can create the same object using a fluent builder provided by the Fabric8 Kubernetes Client model.

Here is an example:

Deployment deployment = new DeploymentBuilder()
        .withNewMetadata()
            .withName("nginx-deployment")
            .addToLabels("app", "nginx")
        .endMetadata()
        .withNewSpec()
            .withReplicas(1)
            .withNewSelector()
                .addToMatchLabels("app", "nginx")
            .endSelector()
        .withNewTemplate()
            .withNewMetadata()
                .addToLabels("app", "nginx")
            .endMetadata()
            .withNewSpec()
                .addNewContainer()
                    .withName("nginx")
                    .withImage("nginx:1.7.9")
                    .addNewPort()
                        .withContainerPort(80)
                    .endPort()
                .endContainer()
            .endSpec()
        .endTemplate()
        .endSpec()
    .build();

How the watch operation functions

Fabric8 Kubernetes Client also provides watch functionality that you can use to observe all the events related to a particular resource. KubernetesClient uses the WebSocket protocol to create watch connections:

try (KubernetesClient client = new KubernetesClientBuilder().build()) {
  Watch watch = client.services()
      .inNamespace("default")
      .watch(new Watcher<>() {
        @Override
        public void eventReceived(Action action, Service service) {
          logger.info("{} {}", action.name(), service.getMetadata().getName());
        }

        @Override
        public void onClose(WatcherException e) {
          logger.info("Watch closing {}", e.getMessage());
        }
      });

  Thread.sleep(10 * 1000L);

  watch.close();
} catch (InterruptedException e) {
  Thread.currentThread().interrupt();
  throw new RuntimeException(e);
}

Although Fabric8 Kubernetes Client's watch functionality is quite robust, I recommend using informers while creating applications that tend to monitor the state of Kubernetes objects for a long time (e.g., Kubernetes Operators). We will discuss this in more detail in a future article in this series.

Use patch operations to update objects

It is also possible to update existing Kubernetes objects using a patch operation. Fabric8 Kubernetes Client provides patch operations using Java objects and plain JSON strings.

For example:

try (KubernetesClient client = new KubernetesClientBuilder().build()) {
  client.services()
      .inNamespace("default")
      .withName("my-service")
      .patch(PatchContext.of(PatchType.STRATEGIC_MERGE), "{\"metadata\":{\"annotations\":{\"foo\":\"bar\"}}}");
}

Learn more about programming Kubernetes in Java

This article demonstrated how to use Fabric8 Kubernetes Client and basic operations. You can find the code in this GitHub repository. The next article, Programming Kubernetes custom resources in Java, describes how to interact with Kubernetes custom resources using its REST API in Java and the Fabric8 Kubernetes Java client.

For more information, check out the Fabric8 Kubernetes Client GitHub page or read the cheat sheet. Feel free to follow the project on these channels:

• StackOverflow
• Twitter
• Gitter Chat