Custom Resource Definitions¶
There are lots of resources predefined in k8s
, like Pod
, Service
, Deployment
, etc.
Still, you can define your own resources. This tutorial, we will go through how to define an nginx
resource.
1. Preparation¶
Make sure you have a k8s
environment to play with. You can choose microk8s
or minikube
to setup a testing environment
2. Custom Resource Definitions¶
We will use the Custom Resource Definitions
to define our new resource. Below is the yaml
of the CRD
.
nginx
Save the following content into nginx-crd.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: nginx.stable.underneathall.com
spec:
group: stable.underneathall.com
scope: Namespaced
names:
plural: nginx
singular: nginx
kind: Nginx
shortNames:
- ngx
versions:
- name: v1
served: true
storage: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
properties:
replicas:
type: integer
Now lets explain the parts step by step.
Version, kind, metadata
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: nginx.stable.underneathall.com
Field | Details |
---|---|
apiVersion | Refers to the k8s ' apiextensions version. For now (2021-Jan), it is v1 |
kind | Must be CustomResourceDefinition |
metadata.name | The value is the plural name of the resource with the group name, in the form: {plural name}.{group name} |
Spec: group, scope and name
spec:
group: stable.underneathall.com
Group name is a way to group all the resources and REST API
s. It's a similar concept to a library name. When the name is set, your apis can be accessed through /apis/<group>
scope: Namespaced
Indicate if this resource is namespace-wide or cluster-wide.
names:
kind: Nginx
singular: nginx
plural: nginx
kind: Nginx
shortNames:
- ngx
Field | Details |
---|---|
kind | The kind name used to create the resource |
singular | Singular name of the resource to use in kubectl |
plural | Plural name of the resource to use in kubectl and API |
shortNames | Short name of the resource to use in kubectl |
Spec: versions
versions:
- name: v1
served: true
storage: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
properties:
replicas:
type: integer
Versions
contain all the available versions.
Field | Details |
---|---|
name | Name of the version |
served | If the version is enabled |
storage | Mark true to let k8s store objects using this version. Only one version can be marked true. |
schema.openAPIV3Schema.type | The type of the schema |
schema.openAPIV3Schema.properties.spec.type | The type of the spec body |
schema.openAPIV3Schema.properties.spec.properties.replicas | The customized field we set |
Now let's create the CRD
Create the CRD
Run:
kubectl apply -f nginx-crd.yaml
Output:
customresourcedefinition.apiextensions.k8s.io/nginx.stable.underneathall.com created
Run:
kubectl get crd nginx.stable.underneathall.com
Output:
NAME CREATED AT
nginx.stable.underneathall.com 2021-01-15T07:10:20Z
3. Create a Nginx Resource¶
New Nginx
Run the following command to save the yaml into nginx.yaml
cat <<NGINX> nginx.yaml
apiVersion: "stable.underneathall.com/v1"
kind: Nginx
metadata:
name: underneathall-nginx
namespace: default
spec:
replicas: 2
NGINX
Run:
kubectl create -f nginx.yaml
Output:
nginx.stable.underneathall.com/underneathall-nginx created
Run:
kubectl get nginx
kubectl get ngx
Output:
NAME AGE
underneathall-nginx 77s
4. Summary¶
In this tutorial, we learnt what a CRD
is composed of, how to create a CRD
, and how to create a customized resource.
However, simply adding a CMD
is not enough. In the Operator tutorial, we will use the CRD
created here and an operator built from scratch to really create a deployment of nginx pods for each Nginx
resource.