From ff0c5fec992dba2ae2981a1464c6e0198d708cc5 Mon Sep 17 00:00:00 2001 From: Lance Ball Date: Wed, 3 Jul 2019 16:33:53 -0400 Subject: [PATCH 1/3] doc: add OpenAPI validation info to user guide The generated YAML CRD created when running `operator-sdk add api ...` includes an OpenAPI v3.0 validation section. E.g. ```YAML validation: openAPIV3Schema: properties: apiVersion: description: 'APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#resources' type: string kind: description: 'Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds' type: string metadata: type: object spec: type: object status: type: object ``` The properties for a CRD should be specified here for validation. In the case of the Memcached example, a `size` property should be added to the generated CRD. This change documents that process in the user guide. --- doc/user-guide.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/doc/user-guide.md b/doc/user-guide.md index b2983ee76c5..cc6f30d0ff0 100644 --- a/doc/user-guide.md +++ b/doc/user-guide.md @@ -106,6 +106,22 @@ After modifying the `*_types.go` file always run the following command to update $ operator-sdk generate k8s ``` +Update the Open API validation section in the CRD at `deploy/crds/cache_v1alpha1_memcached_crd.yaml` so that Kubernetes can validate the properties in a Memcached Custom Resource when it is created or updated. + +```YAML +spec: + validation: + openAPIV3Schema: + properties: + spec: + properties: + size: + type: integer +``` + +To learn more about OpenAPI v3.0 validation schemas in Custom Resource Definitions, refer to the [Kubernetes Documentation][doc_validation_schema]. + + ## Add a new Controller Add a new [Controller][controller-go-doc] to the project that will watch and reconcile the Memcached resource: @@ -619,3 +635,4 @@ When the operator is not running in a cluster, the Manager will return an error [result_go_doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result [metrics_doc]: ./user/metrics/README.md [quay_link]: https://quay.io +[doc_validation_schema]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#specifying-a-structural-schema From a07a5c7946c793a600c84ee47649d5dcdb517857 Mon Sep 17 00:00:00 2001 From: Lance Ball Date: Fri, 5 Jul 2019 12:22:15 -0400 Subject: [PATCH 2/3] squash: incorporate pr review comments --- doc/user-guide.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/user-guide.md b/doc/user-guide.md index cc6f30d0ff0..9bc08f0ccf9 100644 --- a/doc/user-guide.md +++ b/doc/user-guide.md @@ -106,7 +106,12 @@ After modifying the `*_types.go` file always run the following command to update $ operator-sdk generate k8s ``` -Update the Open API validation section in the CRD at `deploy/crds/cache_v1alpha1_memcached_crd.yaml` so that Kubernetes can validate the properties in a Memcached Custom Resource when it is created or updated. +To update the Open API validation section in the CRD `deploy/crds/cache_v1alpha1_memcached_crd.yaml`, run the following command. + +```console +$ operator-sdk generate openapi +``` +This validation section allows Kubernetes to validate the properties in a Memcached Custom Resource when it is created or updated. An example of the generated YAML is as follows: ```YAML spec: @@ -116,6 +121,7 @@ spec: spec: properties: size: + format: int32 type: integer ``` From 9ffc9b43ab8bc3408786ced045187e008d2a49d4 Mon Sep 17 00:00:00 2001 From: Lance Ball Date: Tue, 16 Jul 2019 15:08:02 -0400 Subject: [PATCH 3/3] Update doc/user-guide.md with reviewer suggestion Co-Authored-By: Haseeb Tariq --- doc/user-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/user-guide.md b/doc/user-guide.md index 9bc08f0ccf9..42503c808a7 100644 --- a/doc/user-guide.md +++ b/doc/user-guide.md @@ -106,7 +106,8 @@ After modifying the `*_types.go` file always run the following command to update $ operator-sdk generate k8s ``` -To update the Open API validation section in the CRD `deploy/crds/cache_v1alpha1_memcached_crd.yaml`, run the following command. +### OpenAPI validation +To update the OpenAPI validation section in the CRD `deploy/crds/cache_v1alpha1_memcached_crd.yaml`, run the following command. ```console $ operator-sdk generate openapi