CustomResource Improvements in Fabric8 KubernetesClient v5.0.0

Fabric8 Kubernetes Java Client

Fabric8 Kubernetes Client recently released 5.0.0 version with a focus towards improved support regarding CustomResource and Kubernetes Operator related usage. It’s already integrated into Java Operator SDK.

In this blog, we will be looking at all new improvements in detail. We’ll be looking at the difference in usage in Fabric8 KubernetesClient 5.x versus 4.x versions too. For this blog, let’s consider a simple CustomResource named Book :

apiVersion: testing.fabric8.io/v1alpha1 
kind: Book 
metadata: 
  name: effective-java 
spec: 
  title: "Effective Java" 
  author: "Joshua Bloch" 
  isbn: "0134685997"

It’s based on this CustomResourceDefinition books.testing.fabric8.io :

apiVersion: apiextensions.k8s.io/v1 
kind: CustomResourceDefinition 
metadata: 
  name: books.testing.fabric8.io 
spec: 
  group: testing.fabric8.io 
  versions: 
    - name: v1alpha1 
      served: true 
      storage: true 
      schema: 
        openAPIV3Schema: 
          type: object 
          properties: 
            spec: 
              type: object 
              properties: 
                title: 
                  type: string 
                author: 
                  type: string 
                isbn: 
                  type: string 
            status: 
              type: object 
              properties: 
                issued: 
                  type: boolean 
                issuedto: 
                  type: string       
      subresources: 
        status: {}   
  scope: Namespaced 
  names: 
    plural: books 
    singular: book 
    kind: Book 
    shortNames: 
    - book

You can create this CustomResourceDefinition in your Kubernetes cluster by either using kubectl or using Fabric8 Kubernetes Client like this(Note: you would require ClusterAdmin privileges in order to create a CustomResourceDefinition ):

Creating Book CRD using Fabric8 Kubernetes Client

Okay, once CustomResourceDefinition is applied we can move forward towards checking out new improvements in Fabric8 Kubernetes Client v5.0.0 API.

Defining POJOs for Book CustomResource:

4.x behavior:

Earlier in 4.x versions of KubernetesClient, you needed to provide 4 different kind of POJOs. For example we’re creating CustomResource client for Book CustomResource, we would need to create these POJOs:

• Book.java -> POJO for Book CustomResource
• BookList.java -> POJO for Book ‘s List type
• DoneableBook.java -> POJO required for Doneable interface in Sundrio

Inside the Book CustomResource POJO we would need to provide these two additional POJO’s for spec and status :

• BookSpec.java -> POJO for Book ‘s spec
• BookStatus.java -> POJO for Book ‘s status

Let’s go ahead and take a look at how we define POJOs in 5.x versions of client.

5.x behavior:

In Fabric8 Kubernetes Client 5.x, we’ve gotten rid of Doneable interface and now you don’t need to provide a List type for your CustomResource. It’s being kept as optional, if you don’t provide it KubernetesClient would assume list to be of type KubernetesResourceList<Book>(for a CustomResource of type Book ). This means you would only need to provide these POJOs:

• Book.java -> POJO for Book CustomResource
• BookSpec.java -> POJO for Book ‘s spec
• BookStatus.java -> POJO for Book ‘s status

You also don’t need to provide the CustomResourceDefinitionContext object for CustomResourceDefinition related information. Now, you can provide this information in the form of annotations in your CustomResource POJO itself. As of now, these annotations are supported:

• @Group : Allows to specify CustomResource ApiGroup
• @Version : Allows to specify CustomResource ApiVersion
• @Kind : (Optional)Allows to specify kind to refer to instance of the annotated class. If not provided, a default value is computed based on the annotated class name.
• @Plural : (Optional)Allows to specify the plural form associated with a Custom Resource. If not provided, it will default to a computed value.
• @Singular : (Optional)Allows to specify singular form associated with a Custom Resource. If not provided, it will default to a computed value based on POJO’s class name.

Since every CustomResource requires .spec and .status fields, we have modified CustomResource class in KubernetesClient to a generic class which would require spec and status types respectively. Don’t worry if it sounds a bit confusing, it’ll be a lot clearer when you would look at cleaned up versions of POJOs as per Fabric8 Kubernetes Client 5.0.0.

Let’s take a look at how our POJOs would look for Book CustomResource:

Book.java:

Annotations provided in Book POJO as per Fabric8 Kubernetes Client 5.0.0

You can see how we used @Version and @Group annotations to specify our CRD apiGroup and apiVersion . Book is implementing Namespaced interface since it’s a Namespaced scoped resource.

BookSpec.java:

BookSpec POJO

BookStatus.java:

BookStatus POJO

Creating Book Client:

4.x behavior:

Once you create all these POJO’s you could create this Book CustomResource client like shown below.

Note that just to create Book CustomResource client we had to provide CustomResourceDefinitionContext (object containing details regarding CustomResourceDefinition for Book CustomResource), Book.class , BookList.class and DoneableBook.class which doesn’t seem very readable.

Creating Book CustomResource client in 4.x versions of Fabric8 Kubernetes Client

5.x behavior:

In Fabric8 Kubernetes Client v5.0.0, we’ve gotten rid of these unnecessary arguments in client.customResources() method. You can see that earlier, client.customResources() DSL method which required 4 arguments now only requires one single argument which is the class for that specific CustomResource. It’s totally up to you whether you want to provide BookList type or not. All the CustomResourceDefinition related information is either picked from provided annotations or is build based on opinionated defaults.

New method for creating Book Client in Fabric8 5.x

Okay, apart from how POJOs are defined and how you create a typed client corresponding to your CustomResource( Book in this case); rest of the DSL usage is same as Fabric8 Kubernetes Client 4.x versions.

Let’s take a look at other common operations that we can do with Book ‘s CustomResource client.

Loading CustomResource from YAML to Java object:

Loading a CustomResource YAML manifest into Book object

Listing all CustomResource in a specified namespace:

Listing all CustomResource objects in a specified namespace

Fetching a CustomResource with specific name in some namespace:

Get a Book CustomResource in namespace `default` and name `effective-java`

Create a CustomResource:

Create Book CustomResource

Update a CustomResource:

Updating annotations in already existing CustomResource

Update status subresource in a CustomResource:

Update status subresource of Book custom resource

Watching all CustomResources in a specified namespace:

Watching CustomResource in a specified namespace

Delete a CustomResource:

Deleting a CustomResource with a specified name in some namespace

This concludes today’s blog. I hope I was able to give you an overview of all the CustomResource improvements in Fabric8 Kubernetes Client v5.0.0. You can also check out Migration Guide for 5.0.0 if you’re using 4.x versions of KubernetesClient:

fabric8io/kubernetes-client

You can find all the source code linked in this blog at this github repository:

rohanKanojia/kubernetes-client-demo

Conclusion:

Thanks a lot again for taking time to read this blog! I hope it was helpful. If you like our project please feel free to get involved with us and become a part of our growing community via these channels:

• Create Github Issues when something doesn’t work as expected
• Send us Pull Requests for fixing bugs/adding enhancements
• Chat with us on our Gitter Channel for queries
• Follow us on Twitter