Fix nits in CRD task
This commit is contained in:
Qiming Teng
parent
942fca9b29
commit
321342b3f0
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue