Creating an object from a custom resource definition

You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see [4]

You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see [4]

Kubernetes custom resource definitions

In the Kubernetes API a resource is an endpoint that stores a collection of API objects of a certain kind. For example, the built-in pods resource contains a collection of Pod objects.

A custom resource is an object that extends the Kubernetes API or allows you to introduce your own API into a project or a cluster.

A custom resource definition (CRD) file defines your own object kinds and lets the API Server handle the entire lifecycle.

While only cluster admins can create CRDs, you can create an object from a CRD if you have read and write permission to it.

Creating custom objects from a CRD

Custom objects can contain custom fields that contain arbitrary JSON code.

Prerequisites

  • Create a CRD.

Procedure

  1. Create a YAML definition for the custom object. In the following example definition, the cronSpec and image custom fields are set in a custom object of kind CronTab. The kind comes from the spec.kind field of the custom resource definition object.

    Example YAML file for a custom object

    1. apiVersion: "stable.example.com/v1" (1)
    2. kind: CronTab (2)
    3. metadata:
    4.   name: my-new-cron-object (3)
    5.   finalizers: (4)
    6.   - finalizer.stable.example.com
    7. spec: (5)
    8.   cronSpec: "* * * * /5"
    9.   image: my-awesome-cron-image
    1Specify the group name and API version (name/version) from the custom resource definition.
    2Specify the type in the custom resource definition.
    3Specify a name for the object.
    4Specify the finalizers for the object, if any. Finalizers allow controllers to implement conditions that must be completed before the object can be deleted.
    5Specify conditions specific to the type of object.

  2. After you create the object file, create the object:

    1. oc create -f <file-name>.yaml

Managing custom objects

After you create objects, you can manage your custom resources.

Prerequisites

  • Create a custom resource definition (CRD).

  • Create an object from a CRD.

Procedure

  1. To get information on a specific kind of custom resource, enter:

    1. oc get <kind>

    For example:

    1. oc get crontab
    3. NAME                 KIND
    4. my-new-cron-object   CronTab.v1.stable.example.com

    Note that resource names are not case-sensitive, and you can use either the singular or plural forms defined in the CRD, as well as any short name. For example:

    1. oc get crontabs
    2. oc get crontab
    3. oc get ct

  2. You can also view the raw YAML data for a custom resource:

    1. oc get <kind> -o yaml
    1. oc get ct -o yaml
    3. apiVersion: v1
    4. items:
    5. - apiVersion: stable.example.com/v1
    6.   kind: CronTab
    7.   metadata:
    8.     clusterName: ""
    9.     creationTimestamp: 2017-05-31T12:56:35Z
    10.     deletionGracePeriodSeconds: null
    11.     deletionTimestamp: null
    12.     name: my-new-cron-object
    13.     namespace: default
    14.     resourceVersion: "285"
    15.     selfLink: /apis/stable.example.com/v1/namespaces/default/crontabs/my-new-cron-object
    16.     uid: 9423255b-4600-11e7-af6a-28d2447dc82b
    17.   spec:
    18.     cronSpec: '* * * * /5' (1)
    19.     image: my-awesome-cron-image (1)
    1Custom data from the YAML that you used to create the object displays.