How to Create a Custom Resource Definition (CRD) in Kubernetes

To create a Custom Resource Definition (CRD) in Kubernetes, define a YAML manifest specifying the apiVersion, kind: CustomResourceDefinition, metadata, and the schema under spec. Apply this YAML using kubectl apply -f to register the new resource type in your cluster.

Syntax

A CRD YAML manifest has these main parts:

• apiVersion: Usually apiextensions.k8s.io/v1.
• kind: Always CustomResourceDefinition.
• metadata: Contains the name of the CRD, usually in the form <plural>.<group>.
• spec: Defines the resource details like group, versions, scope, and names.

yaml

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: <plural>.<group>
spec:
  group: <group>
  versions:
    - name: <version>
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                <field>: 
                  type: <type>
  scope: Namespaced
  names:
    plural: <plural>
    singular: <singular>
    kind: <Kind>
    shortNames:
    - <shortname>

Example

This example creates a CRD named crontabs.stable.example.com for a resource called CronTab. It defines a simple spec with a cronSpec string and a image string.

yaml

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
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames:
    - ct

Output

customresourcedefinition.apiextensions.k8s.io/crontabs.stable.example.com created

Common Pitfalls

• Incorrect metadata.name format: It must be <plural>.<group>, or Kubernetes will reject it.
• Missing or invalid schema: The openAPIV3Schema must be valid YAML and describe the resource spec properly.
• Forgetting to set served and storage flags: These control if the version is available and used for storage.
• Scope confusion: Use Namespaced for resources within namespaces or Cluster for cluster-wide resources.

yaml

### Wrong metadata.name example (missing group):
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs
# Correct metadata.name:
metadata:
  name: crontabs.stable.example.com

Quick Reference

Remember these key points when creating a CRD:

• apiVersion: Use apiextensions.k8s.io/v1.
• kind: Always CustomResourceDefinition.
• metadata.name: Must be <plural>.<group>.
• spec.group: Defines the API group.
• spec.versions: List of versions with served and storage flags.
• spec.scope: Namespaced or Cluster.
• spec.names: Defines resource names and short names.

Key Takeaways

Define a CRD YAML with apiVersion apiextensions.k8s.io/v1 and kind CustomResourceDefinition.

metadata.name must be in the format . to register correctly.

Specify the schema under spec.versions[].schema.openAPIV3Schema to validate your custom resource.

Use kubectl apply -f to create the CRD in your Kubernetes cluster.

Check served and storage flags in versions to control API availability and storage version.