whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix nits in CRD task

Browse Source
This commit is contained in:
Qiming Teng
2020-08-28 19:25:10 +08:00
parent 942fca9b29
commit 321342b3f0
1 changed files with 57 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md
+57 -48
View File
@@ -150,7 +150,7 @@ kubectl get ct -o yaml
``` ```
You should see that it contains the custom `cronSpec` and `image` fields 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 ```yaml
apiVersion: v1 apiVersion: v1
@@ -174,7 +174,7 @@ metadata:
## Delete a CustomResourceDefinition ## 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. and delete all custom objects stored in it.
```shell ```shell
@@ -190,11 +190,17 @@ If you later recreate the same CustomResourceDefinition, it will start out empty
## Specifying a structural schema ## 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: 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` * 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` inside of `anyOf` is not specified outside (rule 2).
* `bar`'s `type` is within `anyOf` (rule 3). * `bar`'s `type` is within `anyOf` (rule 3).
* the description is set 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: In contrast, the following, corresponding schema is structural:
```yaml ```yaml
@@ -308,7 +314,7 @@ CustomResourceDefinitions store validated resource data in the cluster's persist
{{< note >}} {{< note >}}
CRDs converted from `apiextensions.k8s.io/v1beta1` to `apiextensions.k8s.io/v1` might lack structural schemas, and `spec.preserveUnknownFields` might be `true`. 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 >}} {{< /note >}}
If you save the following YAML to `my-crontab.yaml`: If you save the following YAML to `my-crontab.yaml`:
@@ -350,12 +356,12 @@ spec:
Notice that the field `someRandomField` was pruned. 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. 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. to clients, `kubectl` also checks for unknown fields and rejects those objects well before they would be sent to the API server.
#### Controlling pruning #### 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: For example:
```yaml ```yaml
@@ -458,7 +464,7 @@ allOf:
With one of those specification, both an integer and a string validate. 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. `x-kubernetes-int-or-string: true` is unfolded to one of the two patterns shown above.
### RawExtension ### 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 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, `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 When the `metadata.deletionTimestamp` field is set, controllers watching the object
execute any finalizers they handle, by polling update requests for that execute any finalizers they handle, by polling update requests for that
@@ -537,7 +543,9 @@ meaning all finalizers have been executed.
### Validation ### Validation
Custom resources are validated via 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: Additionally, the following restrictions are applied to the schema:
@@ -552,17 +560,18 @@ Additionally, the following restrictions are applied to the schema:
- `writeOnly`, - `writeOnly`,
- `xml`, - `xml`,
- `$ref`. - `$ref`.
- The field `uniqueItems` cannot be set to _true_. - The field `uniqueItems` cannot be set to `true`.
- The field `additionalProperties` cannot be set to _false_. - The field `additionalProperties` cannot be set to `false`.
- The field `additionalProperties` is mutually exclusive with `properties`. - 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. Refer to the [structural schemas](#specifying-a-structural-schema) section for other
restrictions and CustomResourceDefinition features.
{{< note >}}
Compare with [structural schemas](#specifying-a-structural-schema) for further restriction required for certain CustomResourceDefinition features.
{{< /note >}}
The schema is defined in the CustomResourceDefinition. In the following example, the The schema is defined in the CustomResourceDefinition. In the following example, the
CustomResourceDefinition applies the following validations on the custom object: 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 ### 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. 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 #### 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). differentiates between columns shown in standard view or wide view (using the `-o wide` flag).
- Columns with priority `0` are shown in standard view. - 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 - `integer` – non-floating-point numbers
- `number` – floating point numbers - `number` – floating point numbers
- `string` – strings - `string` – strings
- `boolean` – true or false - `boolean` – `true` or `false`
- `date` – rendered differentially as time since this timestamp. - `date` – rendered differentially as time since this timestamp.
If the value inside a CustomResource does not match the type specified for the column, 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`. - 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: - Only the following constructs are allowed at the root of the CRD OpenAPI validation schema:
- Description - `description`
- Example - `example`
- ExclusiveMaximum - `exclusiveMaximum`
- ExclusiveMinimum - `exclusiveMinimum`
- ExternalDocs - `externalDocs`
- Format - `format`
- Items - `items`
- Maximum - `maximum`
- MaxItems - `maxItems`
- MaxLength - `maxLength`
- Minimum - `minimum`
- MinItems - `minItems`
- MinLength - `minLength`
- MultipleOf - `multipleOf`
- Pattern - `pattern`
- Properties - `properties`
- Required - `required`
- Title - `title`
- Type - `type`
- UniqueItems - `uniqueItems`
#### Scale subresource #### Scale subresource
When the scale subresource is enabled, the `/scale` subresource for the custom resource is exposed. 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`. 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. - It is a required value.
- Only JSONPaths under `.spec` and with the dot notation are allowed. - 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. 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. - It is a required value.
- Only JSONPaths under `.status` and with the dot notation are allowed. - Only JSONPaths under `.status` and with the dot notation are allowed.
@@ -1141,7 +1150,7 @@ and create it:
kubectl apply -f my-crontab.yaml 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 kubectl get all