Mastering Kubernetes CRDs: Build Custom Resources and Deploy MongoDB Operator

What is a CRD?

CustomResourceDefinition (CRD) is a Kubernetes feature introduced after version 1.7 that lets you extend the Kubernetes API with new resource types without modifying the core source code. A CRD can be namespaced or cluster‑wide, and once created the API server automatically generates a RESTful endpoint for each version.

Creating a CustomResourceDefinition

The following YAML defines a CRD named crontabs.stable.example.com that introduces a new resource kind CronTab with fields cronSpec, image and replicas:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com
spec:
  group: stable.example.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              cronSpec:
                type: string
              image:
                type: string
              replicas:
                type: integer
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames:
    - ct

Key fields:

metadata.name must follow the pattern <plural>.<group>.

spec.group and spec.versions define the API group and version.

scope determines whether the resource is namespaced or cluster‑wide.

names provides human‑readable identifiers such as kind and shortNames.

Apply the CRD

kubectl apply -f crontab-crd.yaml

Creating a Custom Resource Instance

After the CRD is registered, you can create objects of the new type. The example below creates a CronTab instance:

apiVersion: stable.example.com/v1
kind: CronTab
metadata:
  name: my-new-cron-object
spec:
  cronSpec: "* * * * * *"
  image: busybox

kubectl apply -f my-crontab.yaml

Verify the object with kubectl get CronTab – the output shows the newly created resource.

Deploying MongoDB Kubernetes Operator

The MongoDB Kubernetes Operator demonstrates a real‑world use of CRDs and custom controllers. Follow these steps to run it:

Clone the operator repository:

git clone https://github.com/mongodb/mongodb-kubernetes-operator.git

Unzip the release package if you obtained a zip archive.

Create a dedicated namespace: kubectl create ns mongodb Apply the MongoDB CRD provided by the project:

kubectl apply -f deploy/crds/mongodb.com_mongodbcommunity_crd.yaml

Install the operator itself: kubectl apply -f deploy/operator/ -n mongodb Confirm the operator pod is running: kubectl get pods -n mongodb Prepare PersistentVolumes (pv-demo.yaml) for NFS storage and apply them.

Create matching PersistentVolumeClaims (pvc-demo.yaml) and apply them.

Deploy a MongoDB replica‑set custom resource using the manifest in deploy/crds/mongodb.com_v1_mongodbcommunity_cr.yaml.

If pods remain in Pending due to missing PVCs, delete any stale PVCs and recreate them as shown above.

After the PVCs are bound, the MongoDB pods transition to the Running state, confirming a successful deployment of the operator and its custom resources.