Demo Building a Custom Resource Definition

Kubernetes includes built-in types like Deployments, Services, and ConfigMaps, but platform teams often need higher-level, domain-specific abstractions—such as Database or TenantEnvironment—to simplify user workflows. CustomResourceDefinitions (CRDs) let you extend the Kubernetes API with these custom types and enforce server-side validation using openAPIV3Schema. This guide walks through creating a namespaced Database CRD that:

Serves a single API version: v1.
Requires spec.engine and spec.size.
Validates engine and size using enums.
Allows optional version and storage fields.

Only one version entry in spec.versions may have storage: true. This version is used as the persisted storage version in etcd.

CRD structure — key fields and meaning

Below are the important CRD fields you will set. Use the links for more details:

Kubernetes CRD docs: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/

Field	Purpose	Notes / Example
`metadata.name`	The fully-qualified name of the CRD	Must be `<plural>.<group>` — e.g. `databases.platform.example.com`
`spec.group`	API domain (group) for your custom types	e.g. `platform.example.com`
`spec.scope`	Resource scope	`Namespaced` or `Cluster`
`spec.names`	How the resource is referenced (plural, singular, kind, shortNames)	e.g. `plural: databases`, `kind: Database`
`spec.versions`	List of served versions and optional validation schema	Each version may include `schema.openAPIV3Schema` for server-side validation
`schema.openAPIV3Schema`	OpenAPI v3 schema used by the API server to validate custom resources (CRs)	Define `type`, `properties`, `required`, `enum`, etc.

Notes:

The string <plural>.<group> is used as an example for CRD names; when writing docs, wrap such placeholders in backticks: <plural>.<group>.
Use openAPIV3Schema inside spec.versions[*] to perform server-side validation for fields, types, required keys, and enums.

Example CRD YAML: Database

Below is a complete CRD definition for a namespaced Database custom resource. Save this as database-crd.yaml and apply it to your cluster.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  # Must be the fully qualified name: <plural>.<group>
  name: databases.platform.example.com
spec:
  group: platform.example.com
  scope: Namespaced
  names:
    plural: databases
    singular: database
    kind: Database
    shortNames:
      - db
      - dbs
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required:
                - engine
                - size
              properties:
                engine:
                  type: string
                  enum:
                    - postgresql
                    - mysql
                    - mariadb
                size:
                  type: string
                  enum:
                    - small
                    - medium
                    - large
                version:
                  type: string
                storage:
                  type: string

Schema highlights:

The spec object is validated using openAPIV3Schema.
engine and size are required and constrained to specific enum values.
version and storage are optional string fields.

Apply the CRD

Create the database-crd.yaml file (shown above), then apply it:

kubectl apply -f database-crd.yaml

Expected output:

customresourcedefinition.apiextensions.k8s.io/databases.platform.example.com created

Verify the API resource is available:

kubectl api-resources | grep platform

Example output:

databases  db,dbs    platform.example.com/v1   true   Database

Once the CRD is present, you can create Database custom resources. The API server will validate them according to the schema.

Creating Custom Resources (CRs) — examples and validation behaviour

The examples below show common validation errors and a final valid CR. Save each YAML to the noted filename and apply with kubectl apply -f <file>.

Missing metadata.name (invalid)

cr-invalid-name.yaml:

apiVersion: platform.example.com/v1
kind: Database
metadata:
  # name intentionally omitted to demonstrate the error
  namespace: platform-apis
spec:
  engine: mongo
  size: medium

Apply:

kubectl apply -f cr-invalid-name.yaml

Error:

error: error when retrieving current configuration of:
Resource: "platform.example.com/v1, Resource=databases", GroupVersionKind: "platform.example.com/v1, Kind=Database"
Name: "", Namespace: "platform-apis"
from server for: "cr-invalid-name.yaml": resource name may not be empty

Explanation: metadata.name is required for any Kubernetes resource.

Unsupported engine (invalid)

cr-invalid-engine.yaml:

apiVersion: platform.example.com/v1
kind: Database
metadata:
  name: db-order
  namespace: platform-apis
spec:
  engine: mongo
  size: medium

Apply:

kubectl apply -f cr-invalid-engine.yaml

Error:

The Database "db-order" is invalid: spec.engine: Unsupported value: "mongo": supported values: "postgresql", "mysql", "mariadb"

Explanation: spec.engine must match one of the allowed enum values from the CRD (postgresql, mysql, mariadb).

Missing required size (invalid)

cr-missing-size.yaml:

apiVersion: platform.example.com/v1
kind: Database
metadata:
  name: db-order
  namespace: platform-apis
spec:
  engine: mariadb
  # size omitted intentionally

Apply:

kubectl apply -f cr-missing-size.yaml

Error:

The Database "db-order" is invalid: spec.size: Required value

Explanation: spec.size is required by the CRD schema.

Valid CR (successful)

cr-valid.yaml:

apiVersion: platform.example.com/v1
kind: Database
metadata:
  name: db-order
  namespace: platform-apis
spec:
  engine: mariadb
  size: medium
  version: "15"
  storage: 50Gi

Apply:

kubectl apply -f cr-valid.yaml

Expected output:

database.platform.example.com/db-order created

Verify the resource exists (using short name):

kubectl get db -n platform-apis

Example output:

NAME       AGE
db-order   15s

Inspect the resource:

kubectl describe database db-order -n platform-apis

Example (trimmed) output:

Name:         db-order
Namespace:    platform-apis
API Version:  platform.example.com/v1
Kind:         Database
Spec:
  Engine:    mariadb
  Size:      medium
  Version:   15
  Storage:   50Gi

This confirms that:

The API server enforces schema validation.
The custom resource behaves like native Kubernetes resources with kubectl get, kubectl describe, etc.

Troubleshooting tips

If you don’t see your CRD listed after applying, check the API server logs and kubectl get crd output. Also ensure metadata.name in the CRD follows the required <plural>.<group> naming convention and that spec.versions[*].storage is set on only one version.

Common checks:

kubectl get crd databases.platform.example.com -o yaml — inspect what was created.
kubectl api-resources | grep platform — confirm the API resource is registered.
Ensure your cluster version supports apiextensions.k8s.io/v1 (Kubernetes 1.16+).

Summary and best practices

CRDs extend the Kubernetes API to introduce domain-specific object types for your platform.
Use openAPIV3Schema inside spec.versions to enable server-side validation (required fields, enums, types).
Ensure metadata.name of the CRD follows the <plural>.<group> pattern.
Only one spec.versions[*] entry may have storage: true; it determines the persisted version stored in etcd.
After creating a CRD, kubectl and the API server will validate and accept/reject CRs according to the schema you define.

Course Introduction

Platform Architecture and Infrastructure

GitOps and Continuous Delivery

Platform APIs and Self-Service Capabilities

Observability and Operations

Security and Policy Enforcement

Conclusion

Demo Building a Custom Resource Definition

CRD structure — key fields and meaning

Example CRD YAML: Database

Apply the CRD

Creating Custom Resources (CRs) — examples and validation behaviour

Troubleshooting tips

Summary and best practices

Watch Video

Practice Lab

​CRD structure — key fields and meaning

​Example CRD YAML: Database

​Apply the CRD

​Creating Custom Resources (CRs) — examples and validation behaviour

​Troubleshooting tips

​Summary and best practices

Watch Video

Practice Lab

CRD structure — key fields and meaning

Example CRD YAML: Database

Apply the CRD

Creating Custom Resources (CRs) — examples and validation behaviour

Troubleshooting tips

Summary and best practices