List cert-manager CRDs and Document a Field with kubectl explain

Original Prepium guide · Written for Kubernetes v1.35 and checked against the official documentation on 6 October 2026. Use a disposable practice cluster. The example installs one small CustomResourceDefinition of our own, so you can repeat it on any cluster without installing an operator.

Discover custom resources and read their schema from the cluster

Operators extend the Kubernetes API with CustomResourceDefinitions (CRDs). Once a CRD is established, its resource behaves like a built-in one: it appears in API discovery, kubectl can list it, and kubectl explain can document its fields from the schema the API server publishes. When a third-party tool's docs are not at hand, the cluster itself can tell you about its resources.

CRD snapshotpolicies.tutorial.prepium.example  (cluster-scoped object, name = <plural>.<group>)
   └─ adds resource  snapshotpolicies  (kind SnapshotPolicy, group tutorial.prepium.example, v1)
        ├─ kubectl api-resources --api-group=...   discovery view
        ├─ kubectl get crd ...                     the definition objects
        └─ kubectl explain snapshotpolicy.spec...  schema published as OpenAPI

1. Install a CRD with field descriptions

Save this as snapshotpolicy-crd.yaml. The metadata.name must be the plural followed by the group, and each description becomes the text that kubectl explain prints later.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: snapshotpolicies.tutorial.prepium.example
spec:
  group: tutorial.prepium.example
  scope: Namespaced
  names:
    plural: snapshotpolicies
    singular: snapshotpolicy
    kind: SnapshotPolicy
    shortNames:
    - snappol
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            description: Desired snapshot behaviour for one volume.
            properties:
              schedule:
                type: string
                description: Cron expression that decides when snapshots run.
              retention:
                type: object
                description: How many snapshots to keep.
                properties:
                  keepDaily:
                    type: integer
                    description: Number of daily snapshots to retain.

kubectl apply -f snapshotpolicy-crd.yaml
kubectl wait --for=condition=Established crd/snapshotpolicies.tutorial.prepium.example

The API endpoint can take a few seconds to appear, which is why waiting for the Established condition is better than retrying blindly.

2. List what a group added, two different ways

kubectl api-resources --api-group=tutorial.prepium.example -o wide
kubectl get crd | grep prepium
kubectl get crd snapshotpolicies.tutorial.prepium.example -o yaml > /tmp/snappol-crd.yaml

These answer different questions. api-resources reads discovery: resource names, short names, kind, whether it is namespaced, and with -o wide some extra columns. kubectl get crd returns the CRD objects themselves, which are cluster-scoped and can be saved in any kubectl output format (-o yaml, -o name, -o json). When an operator installs several CRDs in one group, filter on the group, not on a word in the kind.

3. Walk the schema with explain

kubectl explain snapshotpolicy
kubectl explain snapshotpolicy --recursive
kubectl explain snapshotpolicy.spec.retention.keepDaily
kubectl explain snapshotpolicies --api-version=tutorial.prepium.example/v1

A field path is the resource name followed by field names separated by dots. Without --recursive, explain shows the description of the node you named plus its direct fields; with it, kubectl also prints the fields of those fields, which is the quickest way to see the shape of a large spec before drilling into one path. --api-version picks a specific group/version when a resource is served in more than one. The same technique works for built-in types, for example kubectl explain deployment.spec.strategy.rollingUpdate. Redirect the output with > to keep it in a file.

4. Prove the new type is usable

kubectl create namespace prepium-tutorial
kubectl -n prepium-tutorial get snappol

An empty list here is a success: the server knows the type and the short name, it just has no objects yet. An unknown-resource-type error instead means the CRD is missing, misnamed or not yet established.

Common mistakes

• Saving kubectl api-resources output when the CRD definitions were wanted, or the reverse: decide whether you need discovery rows or the CRD objects.
• Guessing a field path: run explain one level at a time, or use --recursive first, then copy the exact path.
• Expecting prose for every custom field: explain can only print a description if the CRD's schema includes one; the type and nesting are still shown.
• Asking for instances with kubectl get crd: that lists definitions; instances are listed by the resource name, such as kubectl get snappol -A.

Cleanup: kubectl delete namespace prepium-tutorial and kubectl delete crd snapshotpolicies.tutorial.prepium.example. References: Extend the Kubernetes API with CustomResourceDefinitions, kubectl explain, kubectl api-resources. Next, try working with CRDs (CKAD) or rendering a Helm chart.