diff --git a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md index f9333b01c5..3b51469e56 100644 --- a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md +++ b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md @@ -150,7 +150,7 @@ kubectl get ct -o yaml ``` You should see that it contains the custom `cronSpec` and `image` fields -from the yaml you used to create it: +from the YAML you used to create it: ```yaml apiVersion: v1 @@ -174,7 +174,7 @@ metadata: ## Delete a CustomResourceDefinition -When you delete a CustomResourceDefinition, the server will uninstall the RESTful API endpoint +When you delete a CustomResourceDefinition, the server will uninstall the RESTful API endpoint and delete all custom objects stored in it. ```shell @@ -190,11 +190,17 @@ If you later recreate the same CustomResourceDefinition, it will start out empty ## Specifying a structural schema -CustomResources store structured data in custom fiels (alongside the built-in fields `apiVersion`, `kind` and `metadata`, which the API server validates implicitly). With [OpenAPI v3.0 validation](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation) a schema can be specified, which is validated during creation and updates, compare below for details and limits of such a schema. +CustomResources store structured data in custom fields (alongside the built-in +fields `apiVersion`, `kind` and `metadata`, which the API server validates +implicitly). With [OpenAPI v3.0 validation](#validation) a schema can be +specified, which is validated during creation and updates, compare below for +details and limits of such a schema. -With `apiextensions.k8s.io/v1` the definition of a structural schema is mandatory for CustomResourceDefinitions (in the beta version of CustomResourceDefinition, structural schemas were optional). +With `apiextensions.k8s.io/v1` the definition of a structural schema is +mandatory for CustomResourceDefinitions. In the beta version of +CustomResourceDefinition, the structural schema was optional. -A structural schema is an [OpenAPI v3.0 validation schema](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation) which: +A structural schema is an [OpenAPI v3.0 validation schema](#validation) which: 1. specifies a non-empty type (via `type` in OpenAPI) for the root, for each specified field of an object node (via `properties` or `additionalProperties` in OpenAPI) and for each item in an array node (via `items` in OpenAPI), with the exception of: * a node with `x-kubernetes-int-or-string: true` @@ -274,7 +280,7 @@ is not a structural schema because of the following violations: * `bar` inside of `anyOf` is not specified outside (rule 2). * `bar`'s `type` is within `anyOf` (rule 3). * the description is set within `anyOf` (rule 3). -* `metadata.finalizer` might not be restricted (rule 4). +* `metadata.finalizers` might not be restricted (rule 4). In contrast, the following, corresponding schema is structural: ```yaml @@ -308,7 +314,7 @@ CustomResourceDefinitions store validated resource data in the cluster's persist {{< note >}} CRDs converted from `apiextensions.k8s.io/v1beta1` to `apiextensions.k8s.io/v1` might lack structural schemas, and `spec.preserveUnknownFields` might be `true`. -For migrated CustomResourceDefinitions where `spec.preserveUnknownFields` is set, pruning is _not_ enabled and you can store arbitrary data. For best compatibility, you should update customer resources to meet an OpenAPI schema, and you should set `spec.preserveUnknownFields` true for the CustomResourceDefinition itself. +For migrated CustomResourceDefinitions where `spec.preserveUnknownFields` is set, pruning is _not_ enabled and you can store arbitrary data. For best compatibility, you should update your custom resources to meet an OpenAPI schema, and you should set `spec.preserveUnknownFields` to true for the CustomResourceDefinition itself. {{< /note >}} If you save the following YAML to `my-crontab.yaml`: @@ -350,12 +356,12 @@ spec: Notice that the field `someRandomField` was pruned. This example turned off client-side validation to demonstrate the API server's behavior, by adding the `--validate=false` command line option. -Because the [OpenAPI validation schemas are also published](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#publish-validation-schema-in-openapi-v2) +Because the [OpenAPI validation schemas are also published](#publish-validation-schema-in-openapi-v2) to clients, `kubectl` also checks for unknown fields and rejects those objects well before they would be sent to the API server. #### Controlling pruning -By default, all unspecified fields for a custom resource, across all versions, are pruned. It is possible though to opt-out of that for specifc sub-trees fof fields by adding `x-kubernetes-preserve-unknown-fields: true` in the [structural OpenAPI v3 validation schema](#specifying-a-structural-schema). +By default, all unspecified fields for a custom resource, across all versions, are pruned. It is possible though to opt-out of that for specifc sub-trees of fields by adding `x-kubernetes-preserve-unknown-fields: true` in the [structural OpenAPI v3 validation schema](#specifying-a-structural-schema). For example: ```yaml @@ -458,7 +464,7 @@ allOf: With one of those specification, both an integer and a string validate. -In [Validation Schema Publishing](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#publish-validation-schema-in-openapi-v2), +In [Validation Schema Publishing](#publish-validation-schema-in-openapi-v2), `x-kubernetes-int-or-string: true` is unfolded to one of the two patterns shown above. ### RawExtension @@ -520,7 +526,7 @@ of a resource is not possible while they exist. The first delete request on an object with finalizers sets a value for the `metadata.deletionTimestamp` field but does not delete it. Once this value is set, -entries in the `finalizer` list can only be removed. +entries in the `finalizers` list can only be removed. When the `metadata.deletionTimestamp` field is set, controllers watching the object execute any finalizers they handle, by polling update requests for that @@ -537,7 +543,9 @@ meaning all finalizers have been executed. ### Validation Custom resources are validated via -[OpenAPI v3 schemas](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject) and you can add additional validation using [admission webhooks](/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook). +[OpenAPI v3 schemas](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject) +and you can add additional validation using +[admission webhooks](/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook). Additionally, the following restrictions are applied to the schema: @@ -552,17 +560,18 @@ Additionally, the following restrictions are applied to the schema: - `writeOnly`, - `xml`, - `$ref`. -- The field `uniqueItems` cannot be set to _true_. -- The field `additionalProperties` cannot be set to _false_. +- The field `uniqueItems` cannot be set to `true`. +- The field `additionalProperties` cannot be set to `false`. - The field `additionalProperties` is mutually exclusive with `properties`. -These fields can only be set with specific features enabled: +The `default` field can be set when the [Defaulting feature](#defaulting) is enabled, +which is the case with `apiextensions.k8s.io/v1` CustomResourceDefinitions. +Defaulting is in GA since 1.17 (beta since 1.16 with the `CustomResourceDefaulting` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +enabled, which is the case automatically for many clusters for beta features). -You can also use [Validation Schema Defaulting](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#defaulting) to apply default values. - -{{< note >}} -Compare with [structural schemas](#specifying-a-structural-schema) for further restriction required for certain CustomResourceDefinition features. -{{< /note >}} +Refer to the [structural schemas](#specifying-a-structural-schema) section for other +restrictions and CustomResourceDefinition features. The schema is defined in the CustomResourceDefinition. In the following example, the CustomResourceDefinition applies the following validations on the custom object: @@ -756,7 +765,7 @@ Default values for `metadata` fields of `x-kubernetes-embedded-resources: true` ### Publish Validation Schema in OpenAPI v2 -CustomResourceDefinition [OpenAPI v3 validation schemas](#validation) which are [structural](#specifying-a-structural-schema) and [enable pruning](#preserving-unknown-fields) are published as part of the [OpenAPI v2 spec](/docs/concepts/overview/kubernetes-api/#openapi-and-swagger-definitions) from Kubernetes API server. +CustomResourceDefinition [OpenAPI v3 validation schemas](#validation) which are [structural](#specifying-a-structural-schema) and [enable pruning](#field-pruning) are published as part of the [OpenAPI v2 spec](/docs/concepts/overview/kubernetes-api/#openapi-and-swagger-definitions) from Kubernetes API server. The [kubectl](/docs/reference/kubectl/overview) command-line tool consumes the published schema to perform client-side validation (`kubectl create` and `kubectl apply`), schema explanation (`kubectl explain`) on custom resources. The published schema can be consumed for other purposes as well, like client generation or documentation. @@ -853,7 +862,7 @@ The `NAME` column is implicit and does not need to be defined in the CustomResou #### Priority -Each column includes a `priority` field for each column. Currently, the priority +Each column includes a `priority` field. Currently, the priority differentiates between columns shown in standard view or wide view (using the `-o wide` flag). - Columns with priority `0` are shown in standard view. @@ -866,7 +875,7 @@ A column's `type` field can be any of the following (compare [OpenAPI v3 data ty - `integer` – non-floating-point numbers - `number` – floating point numbers - `string` – strings -- `boolean` – true or false +- `boolean` – `true` or `false` - `date` – rendered differentially as time since this timestamp. If the value inside a CustomResource does not match the type specified for the column, @@ -906,42 +915,42 @@ When the status subresource is enabled, the `/status` subresource for the custom - The `.metadata.generation` value is incremented for all changes, except for changes to `.metadata` or `.status`. - Only the following constructs are allowed at the root of the CRD OpenAPI validation schema: - - Description - - Example - - ExclusiveMaximum - - ExclusiveMinimum - - ExternalDocs - - Format - - Items - - Maximum - - MaxItems - - MaxLength - - Minimum - - MinItems - - MinLength - - MultipleOf - - Pattern - - Properties - - Required - - Title - - Type - - UniqueItems + - `description` + - `example` + - `exclusiveMaximum` + - `exclusiveMinimum` + - `externalDocs` + - `format` + - `items` + - `maximum` + - `maxItems` + - `maxLength` + - `minimum` + - `minItems` + - `minLength` + - `multipleOf` + - `pattern` + - `properties` + - `required` + - `title` + - `type` + - `uniqueItems` #### Scale subresource When the scale subresource is enabled, the `/scale` subresource for the custom resource is exposed. The `autoscaling/v1.Scale` object is sent as the payload for `/scale`. -To enable the scale subresource, the following values are defined in the CustomResourceDefinition. +To enable the scale subresource, the following fields are defined in the CustomResourceDefinition. -- `SpecReplicasPath` defines the JSONPath inside of a custom resource that corresponds to `Scale.Spec.Replicas`. +- `specReplicasPath` defines the JSONPath inside of a custom resource that corresponds to `scale.spec.replicas`. - It is a required value. - Only JSONPaths under `.spec` and with the dot notation are allowed. - - If there is no value under the `SpecReplicasPath` in the custom resource, + - If there is no value under the `specReplicasPath` in the custom resource, the `/scale` subresource will return an error on GET. -- `StatusReplicasPath` defines the JSONPath inside of a custom resource that corresponds to `Scale.Status.Replicas`. +- `statusReplicasPath` defines the JSONPath inside of a custom resource that corresponds to `scale.status.replicas`. - It is a required value. - Only JSONPaths under `.status` and with the dot notation are allowed. @@ -1141,7 +1150,7 @@ and create it: kubectl apply -f my-crontab.yaml ``` -You can specify the category using `kubectl get`: +You can specify the category when using `kubectl get`: ``` kubectl get all