From a26f481492e40bed81ea4a8dd40abc228afda361 Mon Sep 17 00:00:00 2001 From: Nikhita Raghunath Date: Mon, 4 Sep 2017 11:02:53 +0530 Subject: [PATCH] Add docs for CustomResource validation add info about supported fields --- .../extend-api-custom-resource-definitions.md | 122 +++++++++++++++++- .../extend-api-third-party-resource.md | 2 +- 2 files changed, 121 insertions(+), 3 deletions(-) diff --git a/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md b/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md index e6a855b9ac..973722b4fb 100644 --- a/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md +++ b/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md @@ -85,7 +85,7 @@ kind: CronTab metadata: name: my-new-cron-object spec: - cronSpec: "* * * * /5" + cronSpec: "* * * * */5" image: my-awesome-cron-image ``` @@ -137,7 +137,7 @@ items: selfLink: /apis/stable.example.com/v1/namespaces/default/crontabs/my-new-cron-object uid: 9423255b-4600-11e7-af6a-28d2447dc82b spec: - cronSpec: '* * * * /5' + cronSpec: '* * * * */5' image: my-awesome-cron-image kind: List metadata: @@ -171,6 +171,124 @@ This triggers controllers watching the object to execute any finalizers they han Each controller then removes its finalizer from the list and issues the delete request again. This request only deletes the object if the list of finalizers is now empty, meaning all finalizers are done. + +### Validation + +Validation of custom objects is possible via [OpenAPI v3 schema](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject). +Additionally, the following restrictions are applied to the schema: + +- The fields `default`, `nullable`, `discriminator`, `readOnly`, `writeOnly`, `xml` and +`deprecated` cannot be set. +- The field `uniqueItems` cannot be set to true. +- The field `additionalProperties` cannot be set to false. + +This feature is __alpha__ in v1.8 and may change in backward incompatible ways. +Enable this feature using the `CustomResourceValidation` feature gate on +the [kube-apiserver](/docs/admin/kube-apiserver): + +``` +--feature-gates=CustomResourceValidation=true +``` + +The schema is defined in the CustomResourceDefinition. In the following example, the +CustomResourceDefinition applies the following validations on the custom object: + +- `spec.cronSpec` must be a string and must be of the form described by the regular expression. +- `spec.replicas` must be an integer and must have a minimum value of 1 and a maximum value of 10. + +Save the CustomResourceDefinition to `resourcedefinition.yaml`: + +```yaml +apiVersion: apiextensions.k8s.io/v1beta1 +kind: CustomResourceDefinition +metadata: + name: crontabs.stable.example.com +spec: + group: stable.example.com + version: v1 + scope: Namespaced + names: + plural: crontabs + singular: crontab + kind: CronTab + shortNames: + - ct + validation: + # openAPIV3Schema is the schema for validating custom objects. + openAPIV3Schema: + properties: + spec: + properties: + cronSpec: + type: string + pattern: '^(\d+|\*)(/\d+)?(\s+(\d+|\*)(/\d+)?){4}$' + replicas: + type: integer + minimum: 1 + maximum: 10 +``` + +And create it: + +```shell +kubectl create -f resourcedefinition.yaml +``` + +A request to create a custom object of kind `CronTab` will be rejected if there are invalid values in its fields. +In the following example, the custom object contains fields with invalid values: + +- `spec.cronSpec` does not match the regular expression. +- `spec.replicas` is greater than 10. + +If you save the following YAML to `my-crontab.yaml`: + +```yaml +apiVersion: "stable.example.com/v1" +kind: CronTab +metadata: + name: my-new-cron-object +spec: + cronSpec: "* * * *" + image: my-awesome-cron-image + replicas: 15 +``` + +and create it: + +```shell +kubectl create -f my-crontab.yaml +``` + +you will get an error: + +```console +The CronTab "my-new-cron-object" is invalid: []: Invalid value: map[string]interface {}{"apiVersion":"stable.example.com/v1", "kind":"CronTab", "metadata":map[string]interface {}{"name":"my-new-cron-object", "namespace":"default", "deletionTimestamp":interface {}(nil), "deletionGracePeriodSeconds":(*int64)(nil), "creationTimestamp":"2017-09-05T05:20:07Z", "uid":"e14d79e7-91f9-11e7-a598-f0761cb232d1", "selfLink":"", "clusterName":""}, "spec":map[string]interface {}{"cronSpec":"* * * *", "image":"my-awesome-cron-image", "replicas":15}}: +validation failure list: +spec.cronSpec in body should match '^(\d+|\*)(/\d+)?(\s+(\d+|\*)(/\d+)?){4}$' +spec.replicas in body should be less than or equal to 10 +``` + +If the fields contain valid values, the object creation request is accepted. + +Save the following YAML to `my-crontab.yaml`: + +```yaml +apiVersion: "stable.example.com/v1" +kind: CronTab +metadata: + name: my-new-cron-object +spec: + cronSpec: "* * * * */5" + image: my-awesome-cron-image + replicas: 5 +``` + +And create it: + +```shell +kubectl create -f my-crontab.yaml +crontab "my-new-cron-object" created +``` {% endcapture %} {% capture whatsnext %} diff --git a/docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md b/docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md index f66eb69396..c8cde47cf3 100644 --- a/docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md +++ b/docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md @@ -12,7 +12,7 @@ title: Extend the Kubernetes API with ThirdPartyResources ## What is ThirdPartyResource? -**ThirdPartyResource is deprecated as of Kubernetes 1.7 and may be removed in version 1.8 in +**ThirdPartyResource is deprecated as of Kubernetes 1.7 and has been removed in version 1.8 in accordance with the [deprecation policy](/docs/reference/deprecation-policy) for beta features.** **To avoid losing data stored in ThirdPartyResources, you must