19. Custom Resource Definitions in Kubernetes

Overview

In this chapter, we will show how you can use Custom Resource Definitions (CRDs) to extend Kubernetes and add new functionality to your Kubernetes cluster. You will also learn how to define, configure, and implement a complete CRD. We will also describe various example scenarios where CRDs can be very helpful. By the end of this chapter, you will be able to define and configure a CRD and a Custom Resource (CR). You will also learn how to deploy a basic custom controller to implement the required functionality of the CR in your cluster.

Introduction

In previous chapters, we learned about different Kubernetes objects, such as Pods, Deployments, and ConfigMaps. These objects are defined and managed by the Kubernetes API (that is, for these objects, the API server manages their creation and destruction, among other operations). However, you may want to extend the functions provided by Kubernetes to provide a feature that is not shipped with standard Kubernetes, and that cannot be enabled by the built-in objects provided by Kubernetes.

To build these functionalities on top of Kubernetes, we use Custom Resources (CRs). Custom Resource Definitions (CRDs) allow us to add a capability through which users can add custom objects to the Kubernetes server and use those CRs like any other native Kubernetes object. A CRD helps us to introduce our custom objects to the Kubernetes system. Once our CRD is created, it can be used like any other object in the Kubernetes server. Not only that, but we can also use the Kubernetes API...

What Is a Custom Controller?

CRDs and CRs help you define the desired state for your CRs. There is a need for a component that makes sure that the state of the Kubernetes system matches the desired state as defined by the CR. As you have seen in earlier chapters, the Kubernetes components that do this are called controllers. Kubernetes comes up with many of these controllers whose job is to make sure that the desired state (for example, the number of replicas of Pods defined in a Deployment) is equal to the value defined in the Deployment object. In summary, a controller is a component that watches the state of resources through the Kubernetes API server and attempts to match the current state with the desired state.

The built-in controllers that are included in a standard setup of Kubernetes are meant to work with built-in objects such as Deployments. For our CRDs and their CRs, we need to write our own custom controllers.

The Relationship between a CRD, a CR, and a Controller...

Standard Kubernetes API Resources

Let's list all the resources and APIs that are available in the Kubernetes cluster. Recall that everything we have used is defined as an API resource, and an API is a gateway through which we communicate with the Kubernetes server to work with that resource.

Get a list of all the current Kubernetes resources by using the following command:

kubectl api-resources

You should see the following response:

Figure 19.2: Standard Kubernetes API resources

In the preceding screenshot, you can see that the resources defined in Kubernetes have an APIGroup property, which defines what internal API is responsible for managing this resource. The Kind column lists the name of the resources. As we have seen earlier in this topic, for standard Kubernetes objects such as Pods, the schema or definition of a Pod object is built into Kubernetes. When you define a Pod specification to run a Pod, this could be said to be analogous to...

Why We Need Custom Resources?

As stated earlier, CRs provide a way through which we can extend the Kubernetes platform to provide functionalities that are specific to certain use cases. Here are a few use cases where you will encounter the use of CRs.

Example Use Case 1

Consider a use case in which you want to automate the provisioning of a business application or a database onto the Kubernetes cluster automatically. Abstracting away the technical details, such as configuring and deploying the application, allows teams to manage them without having an in-depth knowledge of Kubernetes. For example, you can create a CR to abstract the creation of a database. Thus, users can create a database Pod by just defining the name and size of the database in a CRD, and the controller will provision the rest.

Example Use Case 2

Consider a scenario where you have self-serving teams. Your Kubernetes platform is used by multiple teams and you would like the teams to provision namespaces...

How Our Custom Resources Are Defined

To come up with a solution for Example Use Case 3 in the previous section, we have decided that our CRD will define two fields, as mentioned in the preceding example. To accomplish this, our CR object will look as follows.

apiVersion: "controllers.kube.book.au/v1"
kind: PodLifecycleConfig
metadata:
  name: demo-pod-lifecycle
spec:
  namespaceName: crddemo
  podLiveForThisMinutes: 1

The preceding specification defines our target object. As you can see, it looks just like normal Kubernetes objects, but the specifications (the spec section) are defined as per our requirements. Let's dig a bit deeper into the details.

apiVersion

This is the field required by Kubernetes to group objects. Note that we put the version (v1) as part of the group key. This grouping technique helps us keep multiple versions of our object. Consider whether you want to add a new property without affecting existing users...

Summary

In this chapter, you learned about custom controllers. As per the Kubernetes glossary, a controller implements a control loop to watch the state of the cluster through the API server and makes changes in an attempt to move the current state toward the desired state.

Controllers can not only watch and manage user-defined CRs, but they can also act on resources such as Deployments or services, which are typically part of the Kubernetes controller manager. Controllers provide a way to write your own code to suit your business needs.

CRDs are the central mechanism used in the Kubernetes system to extend its capability. CRDs provide a native way to implement custom logic for the Kubernetes API server that satisfies your business requirements.

You have learned about how CRDs and controllers help provide an extension mechanism for the Kubernetes platform. You have also seen the process through which you can configure and deploy custom controllers on the Kubernetes platform...