What is a CRD (Custom Resource Definition) ?

Custom Resource: A Quick Overview

K8s v1.7 gives you the ability to construct resources according to your needs. With this ability, your object can use any API object with ease. You can consider it as a Kubernetes API extension offering modular Kubernetes.

Developers can add desired capabilities and use fresh custom-designed resources just like the default resources. Here are a few related facts related to custom resources to get familiar with:

• They can show up and vanish from any already-running cluster.
• They don’t rely on the clusters for the updates.
• They enable users to collect and use structured data with full customization.
• They are updated independently by cluster admins.
• Their construction process involves dynamic registration.
• Their construction and permission control is handled using kubectl.

‍

Kubernetes Custom Resource Definition

Required to describe custom resources clearly, K8s custom resource definition is a must-learn for you. It lets you use custom-created resources.

The other way to explain the CRD meaning is: It’s the aid for an end-user to customize Kubernetes. For this, API has to expand and become open for customization. Only after that the resource custom-construction is possible.  

Alone, CRDs are of hardly any help. They will simply mean data. One has to use a customized controller to ensure it is highly-declarative. This controller does the job of keeping the present and expected states in sync with each other. With its help, users basically swell up the Kubernetes behaviors that are important for customization.

Pay attention to the below-mentioned text to understand CRDs in a better way.

• etcd is the storage destination for CRDs
• Core resources and CRDs are kept together
• It’s possible to use features like replication & lifecycle management
• No logical information or particular behavior trait is linked with CRDs
• They survive only to deliver relevant Kubernetes API object creation, exposure, and storing mechanisms.

What more to add here is that CRD-related activities are processed or handled within a kube-apiserver. It is taken care of in the apiextensions-apiserver module, a part of k8s control plane.

When to Use CRDs? 

CRDs are best known for their peerless compatibility with the k8s system. Almost all the k8s components like API clients. UI tools and CLI are delivered best with CRDs. 

We strongly recommend using CRDs if you need all these components to fulfill your development goals.

CRDs are not the best bets to make when you’re looking for a simple development approach. Even though it’s easy to handle CRDs, they are too much to handle. So, use them only if you’re ready to put in that extra effort.

Handling CRDs effectively is only possible by skilled minds. If you’re a rookie developer and are not thorough with Kubernetes, it’s better to avoid CRDs.

‍

Use Cases 

While CRDs are useful for customization, they are not ideal for every situation. They bring the best result when they are used effectively. Let’s try to understand its use case using an example. Suppose, the development goal is to create CI/CD platform and application hosting responsible for lifecycle management.

In such a development scenario, developers have to construct a pipeline that can help in application development, testing, and publishing. Kubernetes clusters will be used for application deployment.

However, default Kubernetes clusters won’t be enough to cater to all deployment needs. Hence, you may utilize custom resources to expand the k8s APIs capabilities. This way, it’s possible for an IT team can have self-service activities during the application development process.

Now, let’s understand CRDs usage practice. In the above example, the k8s custom resource will necessitate user input. Without them, it won’t be easy to conduct the development of Kubernetes.  

The bare minimum setup requirements for this goal are:

• Windows or Linux OS  
• A unique application name denoted by a string identifier
• A supportive programming language like Go, Python, and C#
• Metadata to easily classify the app environment. The permitted values are prod, test, and dev
• A predefined memory and CPU size. Only small, medium, and large values are acceptable
• A minimum replica number that an app can maintain

Use these prerequisites and start constructing the CRDs for customer resources in the given example. 

Creating a CRD 

Always remember that k8s API will generate a new RESTful resource path for every CRD version, cluster-scoped or name-scoped. It happens automatically from the moment you start the CustomResourceDefinition API construction.

Also, keep in mind that if plan to get rid of the namespace of an in-built k8s object, you practically make a move to get rid of all the related custom objects. What about CRDs? Well, they will survive as the CRDs are not namespaced by themselves.

Let’s make a move to understand the CRD construction process for an object of a kind: TestPlatform. Assume that the object is designed to house all the relevant information about the application under construction.

In the Kubernetes custom resource definition example, we have used the example.com API group which may or may not of the company’s domain name.

Understand that the namaspaced location for this resource will be ‘versions’. Let’s begin with ‘v1alpha1’ as this tend to change even before the production commences. A JSON schema has to be declared under the ‘v1alpha1’ version as per specific user input validation rules.

See this example:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
 # name should be a part of form, and must match the below-written spec fields essentially: <plural>.<group>
name: platforms_example.example.com
spec:
 # the name of group to be used for the REST API: /apis/<group>/<version>
 group: example.com
 names:
   # plural is the name that the URL will comprise: /apis/<group>/<version>/<plural>
   plural: platforms_example
   # singular is the alias name to be displayed on the CLI.
   singular: testplatform
   # kind is used by your resource’s manifests and isCamelCased singular type most of the time.
   kind: TestPlatform
   # shortNames lets your resource and shorter string match on the CLI
   shortNames:
   - myp
 # Scope can either be a Cluster type or Namespaced
 scope: Namespaced
 versions:
   - name: v1alpha1
     # Served flag will be able able to enable/disable each version.
     served: true
     # There will be exactly 1 ‘storage’ version.
     storage: true
     schema:
       openAPIV3Schema:
         type: object
         properties:
           spec:
             type: object
             properties:
               appId:
                 type: string
               language:
                 type: string
                 enum:
                 - csharp
                 - python
                 - go
               os:
                 type: string
                 enum:
                 - windows
                 - linux
               instanceSize:
                 type: string
                 enum:
                   - small
                   - medium
                   - large
               environmentType:
                 type: string
                 enum:
                 - dev
                 - test
                 - prod
               replicas:
                 type: integer
                 minimum: 1
             required: ["appId", "language", "environmentType"]
         required: ["spec"]

Now, the second step here is to register it. For this, you need use kubectl apply command as below. 

kubectl apply -f ./crd.yaml

That’s it; CRD is successfully registered. The action to take here is the verification. Use the kubectl get crds command for this job. The other approach is to use the kubectl api-resources | grep testplatform command. Either way, CRD verification will be done swiftly if everything happens as per the standards. 

‍

Create custom objects

Using the registered cluster CRD, it’s easy to create customer objects that will later become a part of customer resources.

apiVersion: example.com/v1alpha1
kind: TestPlatform
metadata:
name: test-example-app
spec:
appId: testexampleapp
language: csharp
os: linux
instanceSize: small
environmentType: development
replicas: 3

This is how anyone can construct custom objects. Suppose you’ve typed kubectl apply -f ./cr.yaml for the registration and you get a message like the below image. 

It’s an error sign signaling the invalid input object. The error takes place because the JSON schema already defined the spec.environmentType field of the custom resource and explained that it was only accepting the enum value of the test, prod, and dev values. So, redefining the same value will show up as an error.  

The key learning here is that it’s better to add validation beforehand with the help of pre-defined schemas values. Just do this and the error will be fixed. Once the error is fixed, run the kubectl apply -f ./cr.yaml command once again and you will see a custom resource instance or record constructing.

apiVersion: example.com/v1alpha1
kind: TestPlatform
metadata:
name: test-example-app
spec:
appId: testexampleapp
language: csharp
os: linux
instanceSize: small
environmentType: dev
replicas: 3

It’s now wise to use the already-in-use kubectl command to the get the custom objects of the CRD. You don’t have to use the full name of CRD as you can retrieve records using the short name as well. 

kubectl get myp  # 

This command will do the job. 

‍

Removing CRD

No longer need a previously created CRD? Don’t worry. 

You can easily erase the Kubernetes CRD with the kubectl delete command. Also, make sure that when you will remove the CRD, automatically the concerned server will eliminate the RESTful API endpoints and every single custom object that those endpoints are storing.

Here is how it goes:

kubectl delete -f resourcedefinition.yaml
kubectl get crontabs
Error from server (NotFound): Unable to list {"stable.example.com" "v1" "crontabs"}: the server could not find the requested resource (get crontabs.stable.example.com)

Once deleted, it’s not possible to retrieve or recreate the same CRD. Even if you try to do so, you’ll get emptied results. 

Conclusion

Kubernetes APIs make container management easier than ever. But, they can become a bit of a headache when they are not flexible as not every requirement is met this way. Custom resources are here to make Kubernetes API a bit more flexible.

Without CRDs, this isn’t possible. The post explained Kubernetes CRDs in detail. Let’s recap the information:

• It’s CRD that instructs API to  be ready for capability expansion.
• CRDs demands custom controller usage to turn mere data into a declarative API.

If you want to look beyond the default capabilities, CRDs are worth considering. But remember, CRDs are effective when they are used in ideal scenarios. So, have your hands on a detailed understanding of K8s custom resource definition first and then make a move.