diff --git a/content/en/blog/_posts/2023-04-24-openapi-v3-field-validation-ga.md b/content/en/blog/_posts/2023-04-24-openapi-v3-field-validation-ga.md new file mode 100644 index 0000000000..1bd1295f97 --- /dev/null +++ b/content/en/blog/_posts/2023-04-24-openapi-v3-field-validation-ga.md @@ -0,0 +1,133 @@ +--- +layout: blog +title: "Server Side Field Validation and OpenAPI V3 move to GA" +date: 2023-04-24 +slug: openapi-v3-field-validation-ga +--- + +**Author**: Jeffrey Ying (Google), Antoine Pelisse (Google) + +Before Kubernetes v1.8 (!), typos, mis-indentations or minor errors in +YAMLs could have catastrophic consequences (e.g. a typo like +forgetting the trailing s in `replica: 1000` could cause an outage, +because the value would be ignored and missing, forcing a reset of +replicas back to 1). This was solved back then by fetching the OpenAPI +v2 in kubectl and using it to verify that fields were correct and +present before applying. Unfortunately, at that time, Custom Resource +Definitions didn’t exist, and the code was written under that +assumption. When CRDs were later introduced, the lack of flexibility +in the validation code forced some hard decisions in the way CRDs +exposed their schema, leaving us in a cycle of bad validation causing +bad OpenAPI and vice-versa. With the new OpenAPI v3 and Server Field +Validation being GA in 1.27, we’ve now solved both of these problems. + +Server Side Field Validation offers resource validation on create, +update and patch requests to the apiserver and was added to Kubernetes +in v1.25, beta in v1.26 and is now GA in v1.27. It provides all the +functionality of kubectl validate on the server side. + +[OpenAPI](https://swagger.io/specification/) is a standard, language +agnostic interface for discovering the set of operations and types +that a Kubernetes cluster supports. OpenAPI V3 is the latest standard +of the OpenAPI and is an improvement upon [OpenAPI +V2](https://kubernetes.io/blog/2016/12/kubernetes-supports-openapi/) +which has been supported since Kubernetes 1.5. OpenAPI V3 support was +added in Kubernetes in v1.23, moved to beta in v1.24 and is now GA in +v1.27. + +## OpenAPI V3 + +### What does OpenAPI V3 offer over V2 + +#### Built-in types + +Kubernetes offers certain annotations on fields that are not +representable in OpenAPI V2, or sometimes not represented in the +OpenAPI v2 that Kubernetes generate. Most notably, the "default" field +is published in OpenAPI V3 while omitted in OpenAPI V2. A single type +that can represent multiple types is also expressed correctly in +OpenAPI V3 with the oneOf field. This includes proper representations +for IntOrString and Quantity. + +#### Custom Resource Definitions + +In Kubernetes, Custom Resource Definitions use a structural OpenAPI V3 +schema that cannot be represented as OpenAPI V2 without a loss of +certain fields. Some of these include nullable, default, anyOf, oneOf, +not, etc. OpenAPI V3 is a completely lossless representation of the +CustomResourceDefinition structural schema. + +### How do I use it? + +The OpenAPI V3 root discovery can be found at the `/openapi/v3` +endpoint of a Kubernetes API server. OpenAPI V3 documents are grouped +by group-version to reduce the size of the data transported, the +separate documents can be accessed at +`/openapi/v3/apis//` and `/openapi/v3/api/v1` +representing the legacy group version. Please refer to the [Kubernetes +API Documentation](/docs/concepts/overview/kubernetes-api/) for more +information around this endpoint. + +Various consumers of the OpenAPI have already been updated to consume +v3, including the entirety of kubectl, and server side apply. An +OpenAPI V3 Golang client is available in +[client-go](https://github.com/kubernetes/client-go/blob/release-1.27/openapi3/root.go). + +## Server Side Field Validation + +The query parameter `fieldValidation` may be used to indicate the +level of field validation the server should perform. If the parameter +is not passed, server side field validation is in `Warn` mode by +default. + +- Strict: Strict field validation, errors on validation failure +- Warn: Field validation is performed, but errors are exposed as + warnings rather than failing the request +- Ignore: No server side field validation is performed + +kubectl will skip client side validation and will automatically use +server side field validation in `Strict` mode. Controllers by default +use server side field validation in `Warn` mode. + +With client side validation, we had to be extra lenient because some +fields were missing from OpenAPI V2 and we didn’t want to reject +possibly valid objects. This is all fixed in server side validation. +Additional documentation may be found +[here](/docs/reference/using-api/api-concepts/#field-validation) + +## What's next? + +With Server Side Field Validation and OpenAPI V3 released as GA, we +introduce more accurate representations of Kubernetes resources. It is +recommended to use server side field validation over client side, but +with OpenAPI V3, clients are free to implement their own validation if +necessary (to “shift things left”) and we guarantee a full lossless +schema published by OpenAPI. + +Some existing efforts will further improve the information available +through OpenAPI including [CEL validation and +admission](/docs/reference/using-api/cel/), along with OpenAPI +annotations on built-in types. + +Many other tools can be built for authoring and transforming resources +using the type information found in the OpenAPI v3. + +## How to get involved? + +These two features are driven by the SIG API Machinery community, +available on the slack channel \#sig-api-machinery, through the +[mailing +list](https://groups.google.com/g/kubernetes-sig-api-machinery) and we +meet every other Wednesday at 11:00 AM PT on Zoom. + +We offer a huge thanks to all the contributors who helped design, +implement, and review these two features. + +- Alexander Zielenski +- Antoine Pelisse +- Daniel Smith +- David Eads +- Jeffrey Ying +- Jordan Liggitt +- Kevin Delgado +- Sean Sullivan