This guide describes how developers can manage Custom Resources (CRs) that come from Custom Resource Definitions (CRDs).

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 Definition (CRD) object defines a new, unique object Kind in the cluster and lets the Kubernetes API server handle its entire lifecycle.

Custom Resource (CR) objects are created from CRDs that have been added to the cluster by a cluster administrator, allowing all cluster users to add the new resource type into projects.

Operators in particular make use of CRDs by packaging them with any required RBAC policy and other software-specific logic.

OpenShift Dedicated cluster administrators can manage RBAC to CRDs that have been added to customer project namespaces, making them available to authorized users.

Creating Custom Resources from a file

After a Custom Resource Definition (CRD) has been added to the cluster, Custom Resources (CRs) can be created with the CLI from a file using the CR specification.

Prerequisites
  • A CRD has been created in your cluster.

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

    Example YAML file for a CR
    apiVersion: "stable.example.com/v1" (1)
    kind: CronTab (2)
    metadata:
      name: my-new-cron-object (3)
      finalizers: (4)
      - finalizer.stable.example.com
    spec: (5)
      cronSpec: "* * * * /5"
      image: my-awesome-cron-image
    1 Specify the group name and API version (name/version) from the Custom Resource Definition.
    2 Specify the type in the CRD.
    3 Specify a name for the object.
    4 Specify the finalizers for the object, if any. Finalizers allow controllers to implement conditions that must be completed before the object can be deleted.
    5 Specify conditions specific to the type of object.
  2. After you create the file, create the object:

    $ oc create -f <file_name>.yaml

Inspecting Custom Resources

You can inspect Custom Resource (CR) objects that exist in your cluster using the CLI.

Prerequisites
  • A CR object exists in a namespace to which you have access.

Procedure
  1. To get information on a specific Kind of a CR, run:

    $ oc get <kind>

    For example:

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

    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:

    $ oc get crontabs
    $ oc get crontab
    $ oc get ct
  2. You can also view the raw YAML data for a CR:

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