Merge pull request #39844 from Jefftree/oas-blog

Blog post for KEP-2896 and KEP-2885

Author: k8s-ci-robot

content/en/blog/_posts/2023-04-24-openapi-v3-field-validation-ga.md

@@ -0,0 +1,133 @@
+---
+layout: blog
+title: "Kubernetes 1.27: 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/<group>/<version>` 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