// Module included in the following assemblies:
//
// * operators/understanding/crds/extending-api-with-crds.adoc

:_mod-docs-content-type: PROCEDURE
[id="crd-creating-custom-resources-definition_{context}"]
= Creating a custom resource definition

To create custom resource (CR) objects, cluster administrators must first create a custom resource definition (CRD).

.Prerequisites

- Access to an {product-title} cluster with `cluster-admin` user privileges.

.Procedure

To create a CRD:

. Create a YAML file that contains the following field types:
+
.Example YAML file for a CRD
[source,yaml]
----
apiVersion: apiextensions.k8s.io/v1 <1>
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com <2>
spec:
  group: stable.example.com <3>
  versions:
    - name: v1 <4>
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                cronSpec:
                  type: string
                image:
                  type: string
                replicas:
                  type: integer
  scope: Namespaced <5>
  names:
    plural: crontabs <6>
    singular: crontab <7>
    kind: CronTab <8>
    shortNames:
    - ct <9>
----
<1> Use the `apiextensions.k8s.io/v1` API.
<2> Specify a name for the definition. This must be in the `<plural-name>.<group>` format using the values from the `group` and `plural` fields.
<3> Specify a group name for the API. An API group is a collection of objects that are logically related. For example, all batch objects like `Job` or `ScheduledJob` could be in the batch API group (such as `batch.api.example.com`). A good practice is to use a fully-qualified-domain name (FQDN) of your organization.
<4> Specify a version name to be used in the URL. Each API group can exist in multiple versions, for example `v1alpha`, `v1beta`, `v1`.
<5> Specify whether the custom objects are available to a project (`Namespaced`) or all projects in the cluster (`Cluster`).
<6> Specify the plural name to use in the URL. The `plural` field is the same as a resource in an API URL.
<7> Specify a singular name to use as an alias on the CLI and for display.
<8> Specify the kind of objects that can be created. The type can be in CamelCase.
<9> Specify a shorter string to match your resource on the CLI.
+
[NOTE]
====
By default, a CRD is cluster-scoped and available to all projects.
====

. Create the CRD object:
+
[source,terminal]
----
$ oc create -f <file_name>.yaml
----
+
A new RESTful API endpoint is created at:
+
[source,terminal]
----
/apis/<spec:group>/<spec:version>/<scope>/*/<names-plural>/...
----
+
For example, using the example file, the following endpoint is created:
+
[source,terminal]
----
/apis/stable.example.com/v1/namespaces/*/crontabs/...
----
+
You can now use this endpoint URL to create and manage CRs. The object kind is based on the `spec.kind` field of the CRD object you created.
