Programming Kubernetes custom resources in Java

Kubernetes 1.16 introduced the concept of custom resources (CRs), allowing users to define their own Kubernetes objects that can be used in their applications. Users are now able to define these Kubernetes object structures tailored to their needs and use them like native Kubernetes resources. This makes Kubernetes much more extensible. These custom resources can be used by Kubernetes Operators to manage applications and their components.

This article is the second installment in this series:

• 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

In this article, you'll see how you can manipulate the Kubernetes custom resource API programmatically in Java using the Fabric8 Kubernetes client. You'll see some common use cases while using Kubernetes custom resources and try to implement those in Java using the Fabric8 Kubernetes client.

Getting the client

The Fabric8 Kubernetes client library should be available on Maven Central. If you're 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 need to add the following to build.gradle:

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

CustomResource POJOs

We're going to consider the Fabric8 Kubernetes client's typed API here, which means we need to provide a CustomResource type to Fabric8 Kubernetes Client. For this, we need to define some plain Java classes as per our CustomResource's structure. We could use tools like Fabric8 Java Generator or Fabric8 CRD Generator to automatically generate these files instead, but we will cover that process in a separate article.

All CustomResources defined to Fabric8 Kubernetes Client must extend the io.fabric8.kubernetes.client.CustomResource class. Let's take a look at that class:

public abstract class CustomResource<S, T> implements HasMetadata {
   // ...
}

As you can see, it's a generic class that seems to have two arguments:

• The first argument is for CustomResource's spec field
• The second argument is for CustomResource's status field

Why does the Fabric8 Kubernetes client require you to have these fields in the CustomResource? All Kubernetes primitive types (except some types in the core and RBAC apiGroups) seem to have spec and status in their bodies. The main motivation behind this is the separation of concerns:

• spec is something that the user specifies. It's the user's way of providing the input for the desired state of that object.
• status is something that should not be modified by the user. It should be the implemented controller/Operator's responsibility to update this field to provide the current state of that object.

The most common application of CustomResources is Kubernetes Operators. Therefore, it's advisable to use spec and status fields when using CustomResources.

Let's take a look at the Java classes for a Book custom resource definition. Here's Book.java:

package io.fabric8.crd.model.v1alpha1;

import io.fabric8.kubernetes.api.model.Namespaced;
import io.fabric8.kubernetes.client.CustomResource;
import io.fabric8.kubernetes.model.annotation.Group;
import io.fabric8.kubernetes.model.annotation.Version;

@Version("v1alpha1")                                             // -> CRD Version
@Group("testing.fabric8.io")                                     // -> CRD Group
public class Book                                                    // -> CRD Kind (if not provided in @Kind annotation)
    extends CustomResource<BookSpec, BookStatus>  // -> .spec -> BookSpec , .status -> BookStatus
    implements Namespaced { }                               // -> CRD scope Namespaced

Here's BookSpec.java:

package io.fabric8.crd.model.v1alpha1;

public class BookSpec {
    private String title;
    private String author;
    private String isbn;

    public String getTitle() {  return title; }

    public void setTitle(String title) { this.title = title; }

    public String getAuthor() { return author; }

    public void setAuthor(String author) { this.author = author; }

    public String getIsbn() { return isbn; }

    public void setIsbn(String isbn) { this.isbn = isbn; }
}

And here's BookStatus.java

package io.fabric8.crd.model.v1alpha1;

public class BookStatus {
    private boolean issued;
    private String issuedto;

    public boolean isIssued() { return issued; }

    public void setIssued(boolean issued) { this.issued = issued; }

    public String getIssuedto() { return issuedto; }

    public void setIssuedto(String issuedto) { this.issuedto = issuedto; }
}

Creating the custom resource definition

Just as you would in Java before creating a custom object, to make a custom resource definition you need to create a class first. In order to use a custom resource, you need to first define its structure and register it to the Kubernetes API server in the form of a CustomResourceDefinition.

We will be taking an example of a simple custom resource called Book. The code snippet below defines the CustomResourceDefinition using the Fabric8 Kubernetes client. It's also possible to automatically generate its YAML file using Fabric8 CRD Generator; we will be covering that in a separate article.

As you can see, we have defined the structure of our custom resource in the openAPIV3Schema field. You can create a CustomResourceDefinition either using kubectl or using Fabric8 Kubernetes Client, like this:

try (KubernetesClient client = new KubernetesClientBuilder().build()) {
      CustomResourceDefinition crd = v1CRDFromCustomResourceType(Book.class)
          .editSpec().editVersion(0)
            .withNewSchema()
              .withNewOpenAPIV3Schema()
                .withType("object")
                .addToProperties("spec", new JSONSchemaPropsBuilder()
                    .withType("object")
                    .addToProperties("title", new JSONSchemaPropsBuilder()
                        .withType("string")
                        .build())
                    .addToProperties("author", new JSONSchemaPropsBuilder()
                        .withType("string")
                        .build())
                    .addToProperties("isbn", new JSONSchemaPropsBuilder()
                        .withType("string")
                        .build())
                    .build())
                .addToProperties("status", new JSONSchemaPropsBuilder()
                    .withType("object")
                    .addToProperties("issued", new JSONSchemaPropsBuilder()
                        .withType("boolean")
                        .build())
                    .addToProperties("issuedto", new JSONSchemaPropsBuilder()
                        .withType("string")
                        .build())
                    .build())
              .endOpenAPIV3Schema()
            .endSchema()
          .endVersion().endSpec().build();

      client.apiextensions().v1()
          .customResourceDefinitions()
          .resource(crd)
          .create();
}

Once you've created Book CustomResourceDefinition, you can start using Book CustomResource.

Basic CRUD operations

If you are already familiar with the Kubernetes client, you'll notice that basic Create, Read, Update, Delete (CRUD) operations for custom resources are not that different from those for regular resources. There is an additional process involved in creating an operation instance for that specific custom resource. Take our Book custom resource as an example. We would need to create a MixedOperation instance like this:

MixedOperation<Book, KubernetesResourceList<Book>, Resource<Book>> bookOp = client.resources(Book.class);

Once you've created this object, you can do basic operations:

try (KubernetesClient client = new KubernetesClientBuilder().build()) {
  // Create Book Client
  MixedOperation<Book, KubernetesResourceList<Book>, Resource<Book>> bookOp = client.resources(Book.class);

  // Create Book Object
  Book book1 = createNewBook("head-first-java", "Head First Java", "Kathy Sierra", "9781491910771");

  // Create
  bookOp.inNamespace("default").resource(book1).create();

  // Read
  book1 = bookOp.inNamespace("default").withName("head-first-java").get();

  // List
  KubernetesResourceList<Book> books = bookOp.inNamespace("default").list();
  books.getItems().stream().map(CustomResource::getMetadata).map(ObjectMeta::getName).forEach(logger::info);

  // Update
  book1.getSpec().setAuthor("Kathy Sierra, Bert Bates, Trisha Gee");
  bookOp.inNamespace("default").resource(book1).replace();

  // Delete
  bookOp.inNamespace("default").resource(book1).delete();
}

Updating status

This use case is very common when working on Kubernetes Operators' control loop. Kubernetes Operators are supposed to update the status of a custom resource after processing it during reconciliation. We will be using the same Book custom resource here and try to update its status:

try (KubernetesClient client = new KubernetesClientBuilder().build()) {
  MixedOperation<Book, KubernetesResourceList<Book>, Resource<Book>> bookOp = client.resources(Book.class);

  // Create Book CR
  Book book1 = createNewBook("effective-java", "Effective Java", "Joshua Bloch ", "9788131726594");
  book1 = bookOp.inNamespace("default").resource(book1).create();

  // Create Status Object
  BookStatus book1Status = new BookStatus();
  book1Status.setIssued(true);
  book1Status.setIssuedto("Bob");

  // Update Status
  book1.setStatus(book1Status);
  bookOp.inNamespace("default").resource(book1).replaceStatus();
}

Custom resource shared informers

While using custom resources in applications, it's better to use shared informers rather than plain watch. It's the same as using shared informers for regular resources, with the additional step of creating a client for the custom resource:

try (KubernetesClient client = new KubernetesClientBuilder().build()) {
  MixedOperation<Book, KubernetesResourceList<Book>, Resource<Book>> bookOp = client.resources(Book.class);

  SharedIndexInformer<Book> bookSharedIndexInformer = bookOp.inNamespace("default").inform(new ResourceEventHandler<>() {
    @Override
    public void onAdd(Book book) { logger.info("{} ADDED"); }

    @Override
    public void onUpdate(Book book, Book t1) { logger.info("{} UPDATED"); }

    @Override
    public void onDelete(Book book, boolean b) { logger.info("{} DELETED"); }
  });

  Thread.sleep(30 * 1000L);
  logger.info("Book SharedIndexInformer open for 30 seconds");

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

Learn more about programming Kubernetes in Java

This article has shown how to manipulate the Kubernetes custom resource API using the Fabric8 Kubernetes client. You can find all the code for this in this repository. The next article, How to use Kubernetes dynamic client with Fabric8, demonstrates the Fabric8 Kubernetes Dynamic Client. 

For more information, check out the Fabric8 Kubernetes Client GitHub page. Feel free to follow us on these channels:

• StackOverflow
• Fabric8 Kubernetes Client CHEATSHEET
• Twitter
• Gitter Chat