In this article, we will talk about how to create a simple Kubernetes Custom Resource by creating a Custom Resource Definition(CRD) with kubectl.
The following topics are covered in this blog.
- What is a Kubernetes Resource
- What is a Custom Resource(CR)
- What is a CustomResourceDefinition(CRD)
- Create a CustomResourceDefinition
- Create a Custom Object
- Add Additional Printer Columns
What is a Kubernetes Resource
In Kubernetes, there are many built-in resources available. Some examples of Kubernetes resources include:
What is a Custom Resource(CR)
A Custom Resource is an object that extends the Kubernetes API or allows you to introduce your own API into a cluster.
Custom resources can appear and disappear in a running cluster through dynamic registration, and cluster admins can update custom resources independently of the cluster itself.
Once a custom resource is installed, users can create and access its objects using kubectl, just as they do for built-in resources like Pods.
What is a CustomResourceDefinition(CRD)
A CustomResourceDefinition (CRD) defines the name and structure of your custom resource that you want to add to the cluster.
CRDs allow users to create new types of custom resources without adding another API server. Defining a CRD object creates a new custom resource with a name and schema that you specify.
When you create a new CRD, the Kubernetes API Server creates a new RESTful resource path to serve and handle the storage of your custom resource. This frees you from writing your own API server to handle the custom resource.
Create a CustomResourceDefinition
Let’s create a simple CRD. Here is the YAML manifest we’ll use. You can save the following CRD to
# name must be in the form: <plural>.<group>
# group name to use for REST API: /apis/<group>/<version>
# kind is normally the CamelCased singular type.
# singular name to be used as an alias on the CLI
# plural name in the URL: /apis/<group>/<version>/<plural>
- name: v1
The next step is to create the CRD using
➜ kubectl apply -f crd.yaml
You’ll get this in response:
Now you can verify it using the
kubectl api-resources | grep myapp command. This command prints the supported API resources on the server.
After using it, you should see the following output:
NAME APIVERSION NAMESPACED KIND
myapps example.com/v1 true MyApp
Create a Custom Object
After the CRD object has been created, you can create custom objects. Custom objects can contain custom fields. These fields can contain arbitrary JSON.
To create the custom object, you’ll use the following YAML manifest:
You can save the above YAML manifest to
test-app.yaml, and create the custom object:
kubectl apply -f test-app.yaml
You can then manage your MyApp objects using kubectl. For example:
kubectl get myapp
Should print a list like this:
Resource names are not case-sensitive when using kubectl, and you can use either the singular or plural forms defined in the CRD, as well as any short names.
You can also view the raw YAML data for a custom resource:
➜ kubectl get myapp test-app -o yaml
Delete a CustomResourceDefinition
When you delete a CustomResourceDefinition, the server will uninstall the RESTful API endpoint and delete all custom objects stored in it.
➜ kubectl delete -f crd.yaml
➜ kubectl get myapp
Error from server (NotFound): Unable to list "example.com/v1, Resource=myapps": the server could not find the requested resource (get myapps.example.com)
If you later recreate the same CustomResourceDefinition, it will start out empty.
Add Additional Printer Columns
The kubectl tool relies on server-side output formatting. Your cluster’s API server decides which columns are shown by the
kubectl get command. You can customize these columns for a CustomResourceDefinition via the
additionalPrinterColumns field. The following example adds the
Save the CustomResourceDefinition to
- name: v1
- name: Replicas
description: The number of pods launched by the MyApp
- name: Version
- name: Age
Create the CustomResourceDefinition:
kubectl apply -f crd.yaml
Create an instance using the
test-app.yaml from the previous section. Invoke the server-side printing:
kubectl get myapp test-app
AGE columns in the output:
NAME REPLICAS VERSION AGE
test-app 3 release-1.0.0 4s
In this article, you learned what a Custom Resource is and how to extend the Kubernetes API using the CRD. You can easily create and access custom resource objects using kubectl, just as they do for built-in resources like Pods.
CRDs are useful when combined with a custom controller and used as a declarative API, ensuring that the current and desired states are always in sync. To learn more about what a Kubernetes controller is, see the article below.
Kubernetes: Controller Overview
What is Controller? Introduction to Kubernetes Controller