apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: pdfdocuments.k8s.startkubernetes.com
spec:
  group: k8s.startkubernetes.com
  scope: Namespaced
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
            type: object
            properties:
                spec:
                  type: object
                  properties:
                    documentName:
                      type: string
                    text:
                      type: string
  names:
    kind: PdfDocument
    singular: pdfdocument
    plural: pdfdocuments
    shortNames:
    - pdf
    - pdfs

Save the YAML to pdf-crd.yaml and create it using kubectl apply -f pdf-crd.yaml.

You can now use pdf, pdfs or pdfdocument to list the PdfDocument resources in the cluster. The resource kind is also visible when you run the api-resources command:

$ kubectl get pdfdocument
No resources found in default namespace.

$ kubectl get pdf
No resources found in default namespace.

$ kubectl api-resources | grep pdf
NAME                              SHORTNAMES   APIGROUP                       NAMESPACED   KIND
...
pdfdocuments                      pdf,pdfs     k8s.startkubernetes.com        true         PdfDocument
...

Kubernetes also creates a new namespaced REST API endpoint for the pdfresources. Let's look at how we can access the API. We will use kubectl proxy command to set up a proxy to the API server this time.

Open a separate terminal window and start the proxy:

$ kubectl proxy --port=8080
Starting to serve on 127.0.0.1:8080

Leave the proxy running, and from a different terminal, you can now access the Kubernetes API. For example, to get the list of all supported APIs, run:

$ curl localhost:8080/apis
...
    {
      "name": "k8s.startkubernetes.com",
      "versions": [
        {
          "groupVersion": "k8s.startkubernetes.com/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "k8s.startkubernetes.com/v1",
        "version": "v1"
      }
    },
...

To access the PdfDocuments API, you have to use the API name and the version, like this:

$ curl localhost:8080/apis/k8s.startkubernetes.com/v1/namespaces/default/pdfdocuments
{"apiVersion":"k8s.startkubernetes.com/v1","items":[],"kind":"PdfDocumentList","metadata":{"continue":"","resourceVersion":"21553","selfLink":"/apis/k8s.startkubernetes.com/v1/namespaces/default/pdfdocuments"}}

We get back an empty list of items, because we haven't created the PdfDocument resource yet. Now that the API is registered and we have the apiVersion, we can create and deploy the PdfDocument. The apiVersion consists of the group name and one of the support versions. In this case, the apiVersion is k8s.startkubernetes.com/v1.

apiVersion: k8s.startkubernetes.com/v1
kind: PdfDocument
metadata:
    name: my-document
spec:
    documentName: my-text
    text: |
        ### This is a title
        Here is some **BOLD** text